From 24f4b5c9e967f0337b4d2f3f0c2a45b4ecfd966b Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Thu, 29 Sep 2022 15:27:28 +0800
Subject: [PATCH] Update release procedures to reflect new PyPI workflow.

---
 docs/how-to/internal/release.rst | 35 ++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/docs/how-to/internal/release.rst b/docs/how-to/internal/release.rst
index 07f754531..5071bc2f4 100644
--- a/docs/how-to/internal/release.rst
+++ b/docs/how-to/internal/release.rst
@@ -44,36 +44,49 @@ The procedure for cutting a new release is as follows:
    * briefcase-iOS-Xcode-template
    * briefcase-android-gradle-template
 
-4. Tag the release, and push the branch and tag upstream::
+4. Tag a release candidate, and push the branch and tag upstream::
 
-    $ git tag v1.2.3
+    $ git tag v1.2.3rc1
     $ git push upstream main
-    $ git push upstream v1.2.3
+    $ git push upstream v1.2.3rc1
 
 5. Pushing the tag will start a workflow to create a draft release on GitHub.
    You can `follow the progress of the workflow on GitHub
    <https://github.com/beeware/briefcase/actions?query=workflow%3A%22Create+Release%22>`__;
    once the workflow completes, there should be a new `draft release
-   <https://github.com/beeware/briefcase/releases>`__.
+   <https://github.com/beeware/briefcase/releases>`__, and an entry on the
+   `Test PyPI server <https://test.pypi.org/project/briefcase/>`__.
 
-6. Log into ReadTheDocs, visit the `Versions tab
+6. Create a clean virtual environment, install the new release from Test PyPI, and
+   perform any pre-release testing that may be appropriate::
+
+    $ python3 -m venv testvenv
+    $ . ./testvenv/bin/activate
+    $ pip install --index-url https://test.pypi.org/simple/ briefcase==1.2.3rc1
+    $ briefcase --version
+    briefcase 1.2.3rc1
+
+7. Log into ReadTheDocs, visit the `Versions tab
    <https://readthedocs.org/projects/briefcase/versions/>`__, and activate the
    new version. Ensure that the build completes; if there's a problem, you
    may need to correct the build configuration, roll back and re-tag the release.
 
-7. Edit the GitHub release. Add release notes (you can use the text generated
+8. Edit the GitHub release. Add release notes (you can use the text generated
    by towncrier). Check the pre-release checkbox (if necessary).
 
-8. Double check everything, then click Publish. This will trigger a
+9. Double check everything, then click Publish. This will trigger a
    `publication workflow on GitHub
    <https://github.com/beeware/briefcase/actions?query=workflow%3A%22Upload+Python+Package%22>`__.
 
-9. Wait for the `package to appear on PyPI
+10. Wait for the `package to appear on PyPI
 <https://pypi.org/project/briefcase/>`__.
 
 Congratulations, you've just published a release!
 
-If anything went wrong during steps 4-6, you will need to delete the draft
-release from GitHub, and push an updated tag. Once the release has successfully
-appeared on PyPI, it cannot be changed; if you spot a problem in a published
+If anything went wrong during steps 4-10, you will need to re-start from step 4
+with a new version number. Once the release has successfully appeared on PyPI
+(or Test PyPI), it cannot be changed; if you spot a problem in a published
 package, you'll need to tag a completely new release.
+
+If the release candidate has been published successfully, you can repeat steps
+4-10 with an acutal release number (i.e., no `rc` suffix).