Merge pull request #231 from consideRatio/pr/test-traefik

Test python 3.12, redis 7, traefik 3 - and misc updates to align with jupyterhub-python-repo-template

.github/workflows/release.yaml

@@ -0,0 +1,52 @@
+# This is a GitHub workflow defining a set of jobs with a set of steps.
+# ref: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
+#
+name: Release
+
+# Always tests wheel building, but only publish to PyPI on pushed tags.
+on:
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - ".github/workflows/*.yaml"
+      - "!.github/workflows/release.yaml"
+  push:
+    paths-ignore:
+      - "docs/**"
+      - ".github/workflows/*.yaml"
+      - "!.github/workflows/release.yaml"
+    branches-ignore:
+      - "dependabot/**"
+      - "pre-commit-ci-update-config"
+    tags: ["**"]
+  workflow_dispatch:
+
+jobs:
+  build-release:
+    name: Build release
+
+    runs-on: ubuntu-22.04
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: install build package
+        run: |
+          pip install --upgrade pip
+          pip install build
+          pip freeze
+
+      - name: build release
+        run: |
+          python -m build --sdist --wheel .
+          ls -l dist
+
+      - name: publish to pypi
+        uses: pypa/gh-action-pypi-publish@release/v1
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          user: __token__
+          password: ${{ secrets.pypi_password }}

.github/workflows/test.yml

@@ -24,10 +24,7 @@ on:
   workflow_dispatch:
 
 env:
-  ETCDCTL_API: "3"
   PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION: python
-  ETCD_DOWNLOAD_VERSION: "3.4.24"
-  CONSUL_VERSION: "1.14.4"
 
 jobs:
   # Run "pytest tests" for various Python versions
@@ -39,68 +36,108 @@ jobs:
       fail-fast: false
       matrix:
         include:
+          # Test against old and new python, and traefik v2 and v3
           - python: "3.8"
-            backend: "etcd"
-          - python: "3.9"
-            backend: "consul"
-          - python: "3.10"
-            backend: "redis"
-          - python: "3.11"
-    steps:
-      # NOTE: In GitHub workflows, environment variables are set by writing
-      #       assignment statements to a file. They will be set in the following
-      #       steps as if would used `export MY_ENV=my-value`.
-      - name: Configure environment variables
-        run: |
-          echo "PATH=$PWD/bin:$PATH" >> $GITHUB_ENV
+            backend: file
+            traefik-version: "v2.10.7"
+          - python: "3.12"
+            backend: file
+            traefik-version: "v3.0.0-beta5"
 
+          # Test each backend that requires a python client against a modern
+          # version of python to ensure clients are compatible.
+          #
+          # - About redis versions:
+          #   redis can be installed from source, as an apt package for an
+          #   ubuntu lts release, or snap package. To avoid complexity we don't
+          #   build from source which would allow us to pick a version to
+          #   install, but we test against the ubuntu and snap package, where
+          #   the ubuntu package typically is behind the snap package.
+          #
+          #   redis-version is provided as a matrix input only to provide
+          #   visibility via github's web UI.
+          #
+          - python: "3.12"
+            backend: redis
+            install-via: apt # version 6.0.16 in ubuntu 22.04, https://packages.ubuntu.com/jammy/redis
+            redis-version: "6.0.16?"
+          - python: "3.12"
+            backend: redis
+            install-via: snap # version 7.2.4 or higher, https://snapcraft.io/redis
+            redis-version: ">=7.2.4"
+          - python: "3.12"
+            backend: etcd
+            etcd-version: "v3.4.29" # https://github.com/etcd-io/etcd/releases
+          - python: "3.12"
+            backend: consul
+            consul-version: "1.17.2" # https://github.com/hashicorp/consul/releases (but omit v prefix)
+    steps:
       - uses: actions/checkout@v4
-      # NOTE: actions/setup-python@v5 make use of a cache within the GitHub base
-      #       environment and setup in a fraction of a second.
-      - name: Install Python ${{ matrix.python }}
-        uses: actions/setup-python@v5
+      - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python }}
 
       - name: Install Python dependencies
         run: |
           pip install --upgrade setuptools pip
-          pip install -r dev-requirements.txt -e .
-          python -m jupyterhub_traefik_proxy.install --output=./bin
+          pip install -e ".[test]"
 
+      - name: List Python dependencies
+        run: |
           pip freeze
+
+      - name: Add bin directories to PATH
+        run: |
+          echo "PATH=$PWD/bin:/snap/redis/current/usr/bin/:$PATH" >> $GITHUB_ENV
+
+      - name: Install traefik
+        run: |
+          TRAEFIK_VERSION=
+          if [[ ! -z "${{ matrix.traefik-version }}" ]]; then
+            TRAEFIK_VERSION=--traefik-version=${{ matrix.traefik-version }}
+          fi
+
+          python -m jupyterhub_traefik_proxy.install --output=./bin ${TRAEFIK_VERSION}
+
+          traefik version
+
       - name: Install consul
         if: matrix.backend == 'consul'
         run: |
-          curl -L https://releases.hashicorp.com/consul/${CONSUL_VERSION}/consul_${CONSUL_VERSION}_linux_amd64.zip > consul.zip
+          curl -L https://releases.hashicorp.com/consul/${{ matrix.consul-version }}/consul_${{ matrix.consul-version }}_linux_amd64.zip > consul.zip
           unzip consul.zip -d ./bin consul
 
+          consul version
+
       - name: Install etcd
         if: matrix.backend == 'etcd'
         run: |
-          curl -L https://github.com/etcd-io/etcd/releases/download/v${ETCD_DOWNLOAD_VERSION}/etcd-v${ETCD_DOWNLOAD_VERSION}-linux-amd64.tar.gz   > etcd.tar.gz
+          curl -L https://github.com/etcd-io/etcd/releases/download/${{ matrix.etcd-version }}/etcd-${{ matrix.etcd-version }}-linux-amd64.tar.gz > etcd.tar.gz
           tar -xzf etcd.tar.gz -C ./bin --strip-components=1 --wildcards '*/etcd*'
 
-      - name: Install redis
-        if: matrix.backend == 'redis'
-        run: |
-          sudo apt-get -y install redis-server
+          etcdctl version
 
-      - name: Select tests
+      - name: Install redis via ${{ matrix.install-via }}
+        if: matrix.backend == 'redis'
         run: |
-          if [[ ! -z "${{ matrix.backend }}" ]]; then
-            # select backend subset
-            echo "PYTEST_ADDOPTS=-k ${{ matrix.backend }}" >> "${GITHUB_ENV}"
+          if [[ "${{ matrix.install-via }}" == "apt" ]]; then
+            sudo apt-get -y install redis
           else
-            # default: select everything _but_ the KV backend tests
-            echo "PYTEST_ADDOPTS=-k 'not etcd and not consul and not redis'" >> "${GITHUB_ENV}"
+            sudo snap install redis
           fi
 
+          redis-server --version
+
       - name: Run tests
         run: |
-          # Using the "--slow-last" flag, should run the slow tests last
-          pytest -v --durations 10 --maxfail 3 --slow-last --color=yes --cov=jupyterhub_traefik_proxy tests
+          if [[ "${{ matrix.backend }}" == "file" ]]; then
+            # select everything _but_ the KV store backend tests
+            export PYTEST_ADDOPTS="-k 'not etcd and not consul and not redis'"
+          else
+            # select backend subset
+            export PYTEST_ADDOPTS="-k ${{ matrix.backend }}"
+          fi
 
-      - name: Submit codecov report
-        run: |
-          codecov
+          pytest
+
+      - uses: codecov/codecov-action@v3

readthedocs.yml → .readthedocs.yaml

@@ -16,7 +16,3 @@ python:
     - method: pip
       path: .
     - requirements: docs/requirements.txt
-
-formats:
-  - htmlzip
-  - epub

CONTRIBUTING.md

@@ -10,14 +10,10 @@ This package requires Python >= 3.6.
 
 As a Python package, you can set up a development environment by cloning this repo and running:
 
-    python3 -m pip install --editable .
+    python3 -m pip install --editable ".[test]"
 
 from the repo directory.
 
-You can also install the tools we use for testing and development with:
-
-    python3 -m pip install -r dev-requirements.txt
-
 ### Auto-format with pre-commit
 
 We use the [pre-commit](https://pre-commit.com) tool for autoformatting.
@@ -35,6 +31,6 @@ If it makes any changes, it'll let you know and you can make the commit again wi
 
 After doing a development install, you can run the tests with:
 
-    pytest -v
+    pytest
 
 in the repo directory.

README.md

@@ -37,22 +37,22 @@ with examples for the three different implementations.
 
 ## Running tests
 
-There are some tests that use _etcdctl_ command line client for etcd. Make sure
-to set environment variable `ETCDCTL_API=3` before running the tests, so that
-the v3 API to be used, e.g.:
+You can then run the all the test suite from the _traefik-proxy_ directory with:
 
 ```
-$ export ETCDCTL_API=3
+$ pytest
 ```
 
-You can then run the all the test suite from the _traefik-proxy_ directory with:
+Or you can run a specific test file with:
 
 ```
-$ pytest -v ./tests
+$ pytest tests/<test-file-name>
 ```
 
-Or you can run a specific test file with:
+There are some tests that use _etcdctl_ command line client for etcd. Make sure
+to set environment variable `ETCDCTL_API=3` before running the tests if etcd
+version 3.3 or older is used, so that the v3 API to be used, e.g.:
 
 ```
-$ pytest -v ./tests/<test-file-name>
+$ export ETCDCTL_API=3
 ```

RELEASE.md

@@ -1,49 +1,53 @@
 # How to make a release
 
-`traefik-proxy` is a package [available on
-PyPI](https://pypi.org/project/jupyterhub-traefik-proxy/). These are
-instructions on how to make a release on PyPI.
+`jupyterhub-traefik-proxy` is a package available on [PyPI].
 
-For you to follow along according to these instructions, you need:
+These are the instructions on how to make a release.
 
-- To have push rights to the [jupyterhub-traefik-proxy GitHub
-  repository](https://github.com/jupyterhub/traefik-proxy).
+## Pre-requisites
+
+- Push rights to this GitHub repository
 
 ## Steps to make a release
 
 1. Create a PR updating `docs/source/changelog.md` with [github-activity] and
-   continue only when its merged.
-
-   ```shell
-   pip install github-activity
+   continue when its merged. For details about this, see the [team-compass
+   documentation] about it.
 
-   github-activity --heading-level=3 jupyterhub/traefik-proxy
-   ```
+   [team-compass documentation]: https://jupyterhub-team-compass.readthedocs.io/en/latest/practices/releases.html
 
-1. Checkout main and make sure it is up to date.
+2. Checkout main and make sure it is up to date.
 
    ```shell
    git checkout main
    git fetch origin main
    git reset --hard origin/main
    ```
 
-1. Update the version, make commits, and push a git tag with `tbump`.
+3. Update the version, make commits, and push a git tag with `tbump`.
 
    ```shell
    pip install tbump
-   tbump --dry-run ${VERSION}
+   ```
+
+   `tbump` will ask for confirmation before doing anything.
 
+   ```shell
+   # Example versions to set: 1.0.0, 1.0.0b1
+   VERSION=
    tbump ${VERSION}
    ```
 
    Following this, the [CI system] will build and publish a release.
 
-1. Reset the version back to dev, e.g. `2.1.0.dev` after releasing `2.0.0`
+4. Reset the version back to dev, e.g. `1.0.1.dev` after releasing `1.0.0`.
 
    ```shell
+   # Example version to set: 1.0.1.dev
+   NEXT_VERSION=
    tbump --no-tag ${NEXT_VERSION}.dev
    ```
 
-[ci system]: https://github.com/jupyterhub/traefik-proxy/actions
 [github-activity]: https://github.com/executablebooks/github-activity
+[pypi]: https://pypi.org/project/jupyterhub-traefik-proxy/
+[ci system]: https://github.com/jupyterhub/traefik-proxy/actions/workflows/release.yaml