Mark a pre-release as one, and keep the docs on the last release during it

Author: craigthackerx

.github/workflows/release.yml

@@ -70,7 +70,14 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
           TAG: ${{ github.ref_name }}
-        run: gh release create "${TAG}" dist/* --verify-tag --generate-notes --title "${TAG}"
+        run: |
+          flags=()
+          # A pre-release (v0.5.1rc1) is marked as one, so it never becomes the latest
+          # release, which is what the weekly patch run rebuilds and people install.
+          if [[ ! "${TAG#v}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            flags+=(--prerelease)
+          fi
+          gh release create "${TAG}" dist/* --verify-tag --generate-notes --title "${TAG}" "${flags[@]}"
 
   # PyPI, through trusted publishing: PyPI trusts this workflow running in the pypi
   # environment, so no token is stored anywhere. It runs last because a version on PyPI

docs/development.md

@@ -77,6 +77,11 @@ tab; the full scan is kept with each run.
 3. `just release`: it checks the tree is clean and in step with `origin/main`, that the
    changelog has the version and the tag is new, then tags and pushes.
 
+A pre-release, for trying a build where only PyPI (or a proxy of it, such as JFrog) can be
+reached, is the same with a version such as `0.5.1rc1`. PyPI takes it, but only asking for that
+version by name (or `--pre`) gets it; the GitHub release is marked a pre-release, and its
+images get only their exact tags, so `latest`, `slim` and the docs stay on the last release.
+
 The release workflow runs CI again as a gate, builds, scans and pushes both images with
 attestations, and only then creates the GitHub release with the wheel, sdist and
 `SHA256SUMS`. A release never exists without its images.

tests/project/test_docs.py

@@ -127,11 +127,16 @@ def test_install_lines_name_the_current_release():
         found
         for page in PAGES
         for found in re.findall(
-            rf"install [^\n]*(?:@v|{re.escape(brand.DISTRIBUTION)}==)(\d+\.\d+\.\d+)",
+            rf"install [^\n]*(?:@v|{re.escape(brand.DISTRIBUTION)}==)"
+            r"(\d+\.\d+\.\d+(?:(?:a|b|rc)\d+|\.dev\d+)?)",
             page.read_text(),
         )
     }
-    assert pinned == {version}
+    if re.fullmatch(r"\d+\.\d+\.\d+", version):
+        assert pinned == {version}
+    else:
+        # A pre-release (0.5.1rc1) is for trying out: the docs stay on the last release.
+        assert len(pinned) == 1, pinned
 
 
 def test_the_readme_pypi_gets_links_to_files_that_exist():