From 997f481093dc5932462746f6f9fce7e8aa564552 Mon Sep 17 00:00:00 2001
From: Mathieu Leplatre <mathieu@mozilla.com>
Date: Mon, 22 Jan 2024 15:52:39 +0100
Subject: [PATCH] Add developer docs and fix release process (#92)

* Add developer docs

* Fix Github Action that releases on Pypi

* Fix environment name
---
 .github/workflows/release.yml | 54 ++++++++++++++++++++++-------------
 docs/development.rst          | 50 ++++++++++++++++++++++++++++++++
 docs/index.rst                |  1 +
 3 files changed, 85 insertions(+), 20 deletions(-)
 create mode 100644 docs/development.rst

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index e1a53dc..2c0c8d2 100644
--- a/.github/workflows/release.yml
+++ b/.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
diff --git a/docs/development.rst b/docs/development.rst
new file mode 100644
index 0000000..8fb2fb7
--- /dev/null
+++ b/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.
diff --git a/docs/index.rst b/docs/index.rst
index 4f0c636..6e2d320 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -64,6 +64,7 @@ Contents
    :maxdepth: 2
    :glob:
 
+   development
    authors
    changelog
    logging