POC for controlled development environment and usage instructions.

.github/workflows/ci.yaml

@@ -4,19 +4,10 @@ on:
   push:
     branches:
       - main
+env:
+  PYTHON_LATEST: "3.10"
 jobs:
-  validate:
-    runs-on: ubuntu-latest
-    env:
-      SETUPTOOLS_USE_DISTUTILS: stdlib
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: "3.10"
-      - uses: pre-commit/action@v3.0.0
   test:
-    needs: validate
     runs-on: ubuntu-latest
     strategy:
       fail-fast: true
@@ -29,30 +20,43 @@ jobs:
         uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
-      - name: Install Poetry
-        uses: snok/install-poetry@v1
-      - name: Load cached venv
-        id: cached-poetry-dependencies
-        uses: actions/cache@v3
+      - name: Install Dependencies
+        run: |
+          python -VV
+          python -m site
+          python -m pip install --upgrade pip setuptools wheel
+          python -m pip install --upgrade virtualenv tox tox-gh-actions
+      - run: "python -m tox"
+      - name: Upload coverage data
+        uses: actions/upload-artifact@v3
         with:
-          path: .venv
-          key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
-      - name: Install dependencies
-        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
-        run: poetry install --no-interaction --no-root --extras="brotli"
-      - name: Set pythonpath
-        run: echo "PYTHONPATH=$PWD" >> $GITHUB_ENV
-      - name: Test
-        run: poetry run pytest
-        if: matrix.python-version != '3.10'
-      - name: Test with Coverage
-        run: poetry run pytest --cov=. --cov-report=xml
-        if: matrix.python-version == '3.10'
-      - uses: actions/upload-artifact@v3
+          name: coverage-data
+          path: "tests/.coverage.*"
+          if-no-files-found: ignore
+  coverage:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+        with:
+          # Use latest Python, so it understands all syntax.
+          python-version: ${{env.PYTHON_LATEST}}
+      - run: python -m pip install --upgrade coverage[toml]
+      - name: Download coverage data
+        uses: actions/download-artifact@v3
+        with:
+          name: coverage-data
+      - name: Combine coverage and upload
+        run: |
+          python -m coverage combine
+          python -m coverage xml -i
+          python -m coverage report -i
+      - name: Upload XML report
+        uses: actions/upload-artifact@v3
         with:
           name: coverage-xml
           path: coverage.xml
-        if: matrix.python-version == '3.10'
   sonar:
     needs: test
     if: github.event.pull_request.head.repo.fork == false

CONTRIBUTING.md

@@ -2,40 +2,51 @@
 
 To contribute code changes or update the documentation, please follow these steps:
 
+## Making changes
+
 1. Fork the upstream repository and clone the fork locally.
-2. Install [poetry](https://python-poetry.org/), and install the project's dependencies with `poetry install`
-3. Install [pre-commit](https://pre-commit.com/) and install the hook by running `pre-commit install`
-4. Make whatever changes and additions you wish and commit these - please try to keep your commit history clean.
-5. Create a pull request to the main repository with an explanation of your changes
+2. Setup a development environment by following the steps below.
+3. Make whatever changes and additions you wish and commit these - please try to keep your commit history clean.
+4. Create a pull request to the main repository with an explanation of your changes
 
 Note: if you add new code or modify existing code - 100% test coverage is mandatory and tests should be well written.
 
----
+## Setup a simple dev environment
 
-## Tox for testing against different versions
+1. Ensure `poetry` is available
 
-### Config
+## Setup a dev environment
 
-1. Install and configure [pyenv](https://github.com/pyenv/pyenv)
-2. Install required python versions via pyenv, e.g., `$ pyenv install 3.x.x` for each required version.
-3. In root directory of library, create .python-version file in root, e.g.:
+1. Install `pyenv` and configure per the instructions for your platform: https://github.com/pyenv/pyenv#installation
+2. Install the specific versions of python you wish to test against, generally this would be latest available point
+   releases, e.g., `$ pyenv install 3.10.5`. (Obsoleted python versions can be cleaned up with `$ pyenv uninstall <version>`)
+3. In root directory of library, create `.python-version` file, and list the versions of python to test against, e.g.:
 
 ```text
+# .python-version
 3.10.5
 3.9.13
 3.8.13
 3.7.13
 ```
 
-4. Restart shell or run command like: `$ pyenv shell 3.10.5 3.9.13 3.8.13 3.7.13`
-5. Remove any existing poetry environment: `$ poetry env remove python`
-6. Tell poetry to use system python <sup>1</sup>: `$ poetry env use system`
-7. `$ poetry install`
+4. Restart shell, run `pyenv local` and the versions listed in `.python-version` should emit to stdout.
+5. If an existing poetry environment exists, can remove with `poetry env remove python`.
+6. Tell poetry to use the preferred python version specified, e.g., `poetry env use 3.10.5`.
+7. Install library and dev dependencies `poetry install --extras "test lint dev"`.
+
+### Existing workflow
+
+If preferred workflow is to interact with `pytest` and `pre-commit` directly, you can do that as
+expected:
+
+- `$ poetry run pytest`
+- `$ pre-commit run --all-files`
 
-1: Not sure if this is the "right" way to handle this yet, however this prevents poetry from reusing
-the local environment in each of the tox environments.
+However, all but the most significant changes should be tested across all supported versions. Doing
+this locally saves having to wait for a CI failure to pick up cross-version errors.
 
-### Run
+### Test against all versions
 
 `$ poetry run tox`