Apply feedback from code review

Author: chrysle

source/guides/github-actions-ci-cd-sample/publish-to-test-pypi.yml

@@ -3,9 +3,45 @@ name: Publish Python 🐍 distributions 📦 to PyPI and TestPyPI
 on: push
 
 jobs:
-  build-n-publish:
-    name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
+  build-n-publish-pypi:
+    name: Build and publish Python 🐍 distributions 📦 to PyPI
     runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/<package-name>
+    permissions:
+      id-token: write
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python3 -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: >-
+        python3 -m
+        build
+        --sdist
+        --wheel
+        --outdir dist/
+        .
+    # Actually publish to PyPI
+    - name: Publish distribution 📦 to PyPI
+      if: startsWith(github.ref, 'refs/tags')
+      uses: pypa/gh-action-pypi-publish@release/v1
+  build-n-publish-testpypi:
+    name: Build and publish Python 🐍 distributions 📦 to TestPyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/<package-name>
     permissions:
       id-token: write
 
@@ -29,11 +65,7 @@ jobs:
         --wheel
         --outdir dist/
         .
-    # Actually publish to PyPI/TestPyPI
     - name: Publish distribution 📦 to Test PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
         repository-url: https://test.pypi.org/legacy/
-    - name: Publish distribution 📦 to PyPI
-      if: startsWith(github.ref, 'refs/tags')
-      uses: pypa/gh-action-pypi-publish@release/v1

source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst

@@ -24,19 +24,23 @@ This guide relies on PyPI's `trusted publishing`_ implementation to connect
 to `GitHub Actions CI/CD`_. This is recommended for security reasons, since 
 the generated tokens are created for each of your projects
 individually and expire automatically. Otherwise you'll need to generate an
-`API token`_ or provide a username/password combination for both PyPI and
-TestPyPI. 
+`API token`_ for both PyPI and TestPyPI. In case of publishing to third-party
+indexes like :doc:`devpi <devpi:index>`, you will need to provide a
+username/password combination.
 
 Since this guide will demonstrate uploading to both
 PyPI and TestPyPI, we'll need two trusted publishers configured. 
-The following steps will lead you through creating the "pending" publishers.
+The following steps will lead you through creating the "pending" publishers
+for your new project. However it is also possible to add `trusted publishing`_
+to any pre-existing project, if you are its owner.
 
 Let's begin! 🚀
 
-1. Go to https://pypi.org/manage/account/publishing/
+1. Go to https://pypi.org/manage/account/publishing/.
 2. Fill in the name you wish to publish your new project under,
-   your repository data and the name of the release workflow file 
-   under the ``.github/`` folder, see :ref:`workflow-definition`. 
+   your GitHub username and repository name and 
+   the name of the release workflow file under 
+   the ``.github/`` folder, see :ref:`workflow-definition`. 
    Finally add the name of the GitHub Actions environment
    running under your repository. 
    Register the trusted publisher.
@@ -74,29 +78,35 @@ should make GitHub run this workflow:
 Defining a workflow job environment
 ===================================
 
-Now, let's add initial setup for our job. It's a process that
-will execute commands that we'll define later.
+We will have to define two jobs to publish to PyPI 
+and TestPyPI respectively.
+
+Now, let's add initial setup for our job that will publish to PyPI.
+It's a process that will execute commands that we'll define later.
 In this guide, we'll use the latest stable Ubuntu LTS version
 provided by GitHub Actions:
 
 .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
    :language: yaml
    :start-after: on:
-   :end-before: steps:
+   :end-before: environment:
 
 
 Checking out the project and building distributions
 ===================================================
 
-Then, add the following under the ``build-n-publish`` section:
+Then, add the following under the ``build-n-publish-pypi`` section:
 
 .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
    :language: yaml
    :start-after: runs-on:
    :end-before: Install pypa/build
 
 This will download your repository into the CI runner and then
-install and activate the newest available Python 3 release.
+install and activate the newest available Python 3 release. It 
+also defines the package index to publish to, PyPI, and grants
+a permission to the action that is mandatory for trusted 
+publishing.
 
 And now we can build dists from source. In this example, we'll
 use ``build`` package.
@@ -114,25 +124,36 @@ So add this to the steps list:
 .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
    :language: yaml
    :start-after: version: "3.x"
-   :end-before: Actually publish to PyPI/TestPyPI
+   :end-before: Actually publish to PyPI
 
 
-Publishing the distribution to PyPI and TestPyPI
-================================================
+Publishing the distribution to PyPI
+===================================
 
 Finally, add the following steps at the end:
 
 .. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
    :language: yaml
-   :start-after: Actually publish to PyPI/TestPyPI
-
-These two steps use the `pypa/gh-action-pypi-publish`_ GitHub
-Action: the first one uploads contents of the ``dist/`` folder
-into TestPyPI unconditionally and the second does that to
-PyPI, but only if the current commit is tagged. It is recommended
-you use the latest release tag; a tool like GitHub's dependabot can keep
+   :start-after: Actually publish to PyPI
+   :end-before: build-n-publish-testpypi
+
+This step uses the `pypa/gh-action-pypi-publish`_ GitHub
+Action: It uploads the contents of the ``dist/`` folder
+into PyPI unconditionally, but only if the current commit 
+is tagged. It is recommended you use the latest release 
+tag; a tool like GitHub's dependabot can keep
 these updated regularly.
 
+Separate workflow for publishing to TestPyPI
+============================================
+
+Now, repeat these steps and create another job for
+publishing to the TestPyPI package index under the ``jobs``
+section:
+
+.. literalinclude:: github-actions-ci-cd-sample/publish-to-test-pypi.yml
+   :language: yaml
+   :start-after: uses: pypa/gh-action-pypi-publish@release/v1
 
 That's all, folks!
 ==================