Add developer docs and fix release process

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: Release
+name: Publish Python 🐍 distribution 📦 to PyPI
 
 on:
   push:
@@ -7,33 +7,47 @@ on:
 
 jobs:
   build:
+    name: Build distribution 📦
     if: github.repository == 'mozilla-services/python-dockerflow'
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: 3.8
 
-      - name: Install dependencies
-        run: |
-          python -m pip install -U pip
-          python -m pip install -U setuptools twine wheel
-
-      - name: Build packages
-        run: |
-          python setup.py --version
-          python setup.py sdist --format=gztar bdist_wheel
-          twine check dist/*
-
-      - name: Upload packages to PyPI
-        if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-        run: twine upload dist/*
-        env:
-          TWINE_USERNAME: ${{ secrets.TWINE_USERNAME }}
-          TWINE_PASSWORD: ${{ secrets.TWINE_PASSWORD }}
+      - name: Install pypa/build
+        run: python3 -m pip install build
+
+      - name: Build a binary wheel and a source tarball
+        run: python3 -m build
+
+      - name: Store the distribution packages
+        uses: actions/upload-artifact@v3
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish Python 🐍 distribution 📦 to PyPI
+    needs:
+      - build
+    runs-on: ubuntu-latest
+    environment:
+      name: release
+      url: https://pypi.org/p/dockerflow
+    permissions:
+      id-token: write
+    steps:
+      - name: Download all the dists
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution 📦 to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

docs/development.rst

@@ -0,0 +1,50 @@
+Development
+===========
+
+
+Setup
+-----
+
+**Requirements**
+
+- `tox <https://tox.wiki>`_
+- `Redis <https://redis.io/>`_
+
+
+Run tests
+---------
+
+Run a local Redis:
+
+::
+
+    docker run redis -p 6379:6379
+
+Run the test suite:
+
+::
+
+    tox -v
+
+For a specific framework or version (see ``tox.ini`` for available environments):
+
+::
+
+    tox -e py311-fl22
+
+Pass arguments to ``pytest`` using the ``--`` delimiter:
+
+::
+
+    tox -e py311-fl22 -- -x tests/flask/test_flask.py
+
+
+Release
+-------
+
+1. Update the changelog in ``docs/changelog.rst``
+2. Tag using `Calver <https://calver.org/>`_
+3. Push tag to Github
+4. Create release entry in repository
+
+A Github Action will be triggered and publish the package to Pypi.

docs/index.rst

@@ -64,6 +64,7 @@ Contents
    :maxdepth: 2
    :glob:
 
+   development
    authors
    changelog
    logging