docs, skill: document the YAML-declared version workflow

Signed-off-by: Ludovic Henry <git@ludovic.dev>

Author: luhenry

docs/development.md

@@ -35,16 +35,55 @@ The general process:
 2. Create a copy of the upstream build workflow in the `python-wheels` repo at
    `.github/workflows/build-<package>.yml`, where `<package>` matches the
    project name (e.g. `build-numpy.yml` for NumPy`).
-3. Remove any workflow logic not related to the Linux glibc and musl (if
+3. Create `docs/packages/<package>.yaml` declaring the version to build (see
+   [Declaring Versions](#declaring-versions)).
+4. Remove any workflow logic not related to the Linux glibc and musl (if
    present) build processes, support for other architectures and operating
    systems (e.g. Windows, Mac OS). This includes the sdist build (unless it is
    consumed by a build or test step).
-4. Repeat steps #2 and #3 for the corresponding test workflow, if it is separate
+5. Repeat steps #2 and #4 for the corresponding test workflow, if it is separate
    from the upstream build file.
 
 From this point, some customizations are required to enable builds targeting
 riscv64.
 
+## Declaring Versions
+
+`docs/packages/<package>.yaml` is the source of truth for what a workflow
+builds. A brand-new package starts with:
+
+```yaml
+package-name: <package>
+source-code: <repository URL>
+license: <SPDX identifier>
+versions:
+- version: <version>
+```
+
+`version` is the version the built wheel will carry (its `METADATA` version,
+not necessarily the git tag: the workflow derives the tag from it). An entry
+with no `tag:` and no `files:` is **pending**: it has not been released yet.
+`_setup.yml` reads the YAML at the start of every run and hands the list of
+pending versions to the build jobs as a matrix, so:
+
+- a `pull_request` run builds every pending version and dry-runs the publish;
+- a `push` to `main` builds every pending version and publishes it;
+- a `workflow_dispatch` with a `version` glob (e.g. `2.5.*`) rebuilds every
+  matching version, released or not, and republishes it from `main`;
+- a run with nothing pending (typically the push that lands `tag:`/`files:`)
+  skips every job and stays green.
+
+Publishing fills in `tag:`/`files:` under that entry through the documentation
+PR (`ci_scripts/update_doc.py`), which retires it from the pending set. The
+wheel's version must match a declared entry byte for byte, or the publish
+fails: a `setuptools_scm` dev version (`1.0.1.dev0+g...`) where `1.0.0` was
+declared is a bug in the build, not something to document.
+
+To **upgrade** an existing package, append a `- version: <new version>` line to
+its YAML and open a PR; no workflow change is needed unless the new version
+needs one. The nightly `check_versions.py` opens exactly that PR
+automatically.
+
 ## Workflow Customizations for riscv64
 
 ### riscv64 Runners
@@ -129,26 +168,81 @@ when invoked.
 ### Using the python-wheels Repository in Workflows
 
 The `python-wheels` repository contains reusable workflows and patch files to
-apply for certain projects. Every `build-<package>.yml` workflow calls
-`_publish-wheel.yml`, which performs the following steps:
+apply for certain projects. Every `build-<package>.yml` workflow starts with a
+`setup` job that calls `_setup.yml` to turn the package YAML into the version
+matrix, and every other job iterates over that matrix:
+
+```
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version glob to (re)build; empty builds every version of docs/packages/numpy.yaml not released yet'
+        required: false
+        default: ''
+  pull_request:
+    branches: [main]
+    paths:
+      - '.github/workflows/build-numpy.yml'
+      - 'docs/packages/numpy.yaml'
+  push:
+    branches: [main]
+    paths:
+      - '.github/workflows/build-numpy.yml'
+      - 'docs/packages/numpy.yaml'
+
+jobs:
+  setup:
+    uses: $/.github/workflows/_setup.yml
+    with:
+      package: numpy
+      version: ${{ inputs.version }}
+
+  build_wheels:
+    needs: [setup]
+    if: needs.setup.outputs.versions != '[]'
+    name: Build numpy ${{ matrix.version }} ${{ matrix.python }}-manylinux_riscv64
+    strategy:
+      fail-fast: false
+      matrix:
+        version: ${{ fromJSON(needs.setup.outputs.versions) }}
+        python: ["cp312", "cp313", "cp314", "cp314t"]
+    env:
+      NUMPY_VERSION: ${{ matrix.version }}
+    ...
+```
+
+The `if:` guard is required: GitHub Actions rejects a job whose matrix vector is
+empty, and `versions` is `[]` whenever nothing is pending. Job outputs are not
+per matrix leg, so a job must not hand its version to another through
+`outputs:`; use `matrix.version` (or an artifact named after it) instead.
+
+Every `build-<package>.yml` workflow ends with a call to `_publish-wheel.yml`,
+which performs the following steps:
 
 1. Downloads the built wheel(s) from the previous job
 2. Creates an immutable GitHub Release containing the wheels
-3. Opens a PR against `docs/packages/<name>.yaml` documenting the new version
-   (via `ci_scripts/update_doc.py`), which `ci_scripts/generate_packages_doc.py`
-   later renders into the published Markdown page. With it in place, the
-   `build-numpy.yml` script's `publish` job looks like this:
+3. Opens a PR against `docs/packages/<name>.yaml` recording the release under
+   the version's entry (via `ci_scripts/update_doc.py`), which
+   `ci_scripts/generate_packages_doc.py` later renders into the published
+   Markdown page. With it in place, the `build-numpy.yml` script's `publish`
+   job looks like this:
 
 ```
 publish:
-  name: Publish numpy ${{ inputs.version || '2.5.0' }}
-  needs: build_wheels
+  name: Publish numpy ${{ matrix.version }}
+  needs: [setup, build_wheels]
+  if: needs.setup.outputs.versions != '[]'
+  strategy:
+    fail-fast: false
+    matrix:
+      version: ${{ fromJSON(needs.setup.outputs.versions) }}
   permissions:
     contents: write
     pull-requests: write
   uses: $/.github/workflows/_publish-wheel.yml
   with:
-    artifact-pattern: numpy-${{ inputs.version || '2.5.0' }}-*-manylinux_riscv64
+    artifact-pattern: numpy-${{ matrix.version }}-*-manylinux_riscv64
 ```
 
 `permissions` needs `contents: write` and `pull-requests: write` here (not just
@@ -161,15 +255,16 @@ the example.
 
 ## Testing a New Workflow
 
-Open a new draft PR with the workflow(s) included, and include a `Trigger:` line
-in the PR description with a version for each package version you want to build,
-like so:
+Open a new draft PR with the workflow and the package YAML. The `pull_request`
+trigger runs the workflow, which builds every version the YAML declares as
+pending; to build additional versions, add more `- version:` lines. To force a
+rebuild of an already released version, dispatch the workflow on the PR branch
+with a version glob:
 
-`Trigger: numpy:v2.5.0`
-`Trigger: numpy:v2.5.1`
+`gh workflow run build-numpy.yml --ref <branch> -f version='2.5.*'`
 
-The repository's automation logic will pick up on and trigger the appropriate
-build workflows for each version. Achieving a passing (green) build may require
+(A brand-new workflow can only be dispatched once its first `pull_request` run
+has registered it with GitHub.) Achieving a passing (green) build may require
 several attempts including rework and possible patches, depending on the nature
 of the failure.
 
@@ -222,22 +317,29 @@ in dry-run mode. Review the publish job and confirm that it selected exactly the
 expected wheels and derived the expected normalized package name and version.
 Pull request runs never create releases or documentation pull requests.
 
-Merging the pull request does not publish its artifacts. After merge, a
-maintainer must dispatch the package workflow again from the `main` branch with
-the reviewed version. The successful `main` run:
+Merging the pull request pushes the pending version to `main`, which triggers
+the package workflow again through its `push` trigger. The successful `main`
+run:
 
 1. creates a draft GitHub Release targeting the workflow's commit;
 2. names the release `<normalized-package>-v<version>` and gives its tag a UTC
    timestamp suffix, `<normalized-package>-v<version>-<yyyymmddhhmmss>`;
 3. uploads all selected wheels and any required `gpl-sources.tar` asset;
 4. publishes the release, at which point repository-level immutable releases
    freeze its tag and assets; and
-5. opens or updates the shared documentation pull request with the release tag,
-   wheel filenames, SHA-256 hashes, and `Requires-Python` metadata.
+5. opens or updates the shared documentation pull request, filling in the
+   version's entry with the release tag, wheel filenames, SHA-256 hashes, and
+   `Requires-Python` metadata.
 
 Every `main` run creates a new release; existing releases are never reused or
 modified. Its description links back to the workflow run that produced it.
-Publishing fails if immutable releases are disabled.
+Publishing fails if immutable releases are disabled, or if the wheel's version
+is not declared in the package YAML.
+
+Merging the documentation pull request pushes the now-released entry to `main`
+and triggers the workflow once more; with nothing left pending, that run skips
+every job. Until then the version is still pending, so any other push touching
+the workflow or its YAML rebuilds and re-releases it.
 
 The generated `/simple/` package index reads only `docs/packages/*.yaml`. The
 new release does not become discoverable through pip until the generated

docs/workflows.md

@@ -17,17 +17,20 @@ considered sufficient without user review. For best practices, reference
 1. Workflows should be designed to mirror the upstream equivalents' linux +
    glibc build/test processes, deviating only where necessary and with
    documentation as to why.
-2. **A brand-new `build-<package>.yml` must keep both the `workflow_dispatch`
-   and `pull_request: paths` triggers.** GitHub only lets you dispatch a
-   workflow that has already produced at least one run on the repository; a
-   file that exists solely on a PR branch is not yet registered, so
-   `workflow_dispatch` and a `Trigger:` line (see below) both fail with
-   `HTTP 404`. The `pull_request: paths` run from opening the PR is what
-   registers it. Never drop this trigger to "avoid a duplicate CI run" it's
-   the only way a new package's build ever starts.
+2. **A brand-new package is two files: `build-<package>.yml` and
+   `docs/packages/<package>.yaml`.** The YAML declares the versions to build
+   (see [Declaring Versions](development#declaring-versions)); the workflow
+   must keep all three triggers, `workflow_dispatch`, `pull_request: paths`
+   and `push: paths`, each pointing at both files. GitHub only lets you
+   dispatch a workflow that has already produced at least one run on the
+   repository; a file that exists solely on a PR branch is not yet registered,
+   so a `workflow_dispatch` fails with `HTTP 404`. The `pull_request: paths`
+   run from opening the PR is what registers it, and builds the pending
+   versions. Never drop this trigger to "avoid a duplicate CI run" it's the
+   only way a new package's build ever starts.
 3. The `_publish-wheel.yml` reusable workflow must be used in place of any
    upstream deployment procedure. It performs a dry run on pull requests and
-   publishes immutable GitHub Releases when dispatched from `main`. In
+   publishes immutable GitHub Releases when run from `main`. In
    particular, the contributor **must** check that the correct number of wheels
    are generated and selected for upload.
 4. Built wheels need to be inspected for license compliance, both to ensure that
@@ -37,21 +40,21 @@ considered sufficient without user review. For best practices, reference
    the build environment's `gcc`) end up linked into a wheel, the
    `collect-gpl-sources` action must be used to publish those sources
    permanently alongside the release.
-5. After the contribution is merged, a maintainer must dispatch the workflow
-   again from `main`. That run creates a new immutable GitHub Release and opens
-   or updates the shared documentation PR. The release becomes visible through
-   the RISE Simple API only after that documentation PR is reviewed, merged,
-   and deployed. The maintainer also opens (or reuses) a tracking issue for the
-   package and links it to the PR.
+5. Merging the contribution pushes the pending version to `main`, which runs
+   the workflow again through its `push` trigger. That run creates a new
+   immutable GitHub Release and opens or updates the shared documentation PR.
+   The release becomes visible through the RISE Simple API only after that
+   documentation PR is reviewed, merged, and deployed. The maintainer also
+   opens (or reuses) a tracking issue for the package and links it to the PR.
 
 ## Reviewing a Documentation PR
 
 Documentation updates are generated as part of the `_publish-wheel.yml`
 workflow, which runs `ci_scripts/update_doc.py` against every newly built wheel.
-Each version's YAML entry records immutable release tags and, for every wheel,
-the filename, SHA-256 hash, and optional `Requires-Python` value. These YAML
-files are the source of truth for both the package documentation and the static
-Simple API. This is separate from `.github/workflows/website.yml`, which builds
+It fills in the version's declared entry with the immutable release tag and,
+for every wheel, the filename, SHA-256 hash, and optional `Requires-Python`
+value. These YAML files are the source of truth for both the package
+documentation and the static Simple API. This is separate from `.github/workflows/website.yml`, which builds
 and deploys the site, including documentation previews. The generated
 pull requests need to be checked against the following criteria:
 
@@ -67,11 +70,12 @@ pull requests need to be checked against the following criteria:
    license text in the documentation file. This should be replaced with the
    actual license type. For valid license strings, review the [SPDX
    list](https://spdx.org/licenses/).
-3. Each version entry must contain the latest release tag and list every
-   expected wheel with the correct filename, SHA-256 hash, and
-   `Requires-Python` value. If the package linked against one or more
-   GPL-licensed projects, the same version entry must also record its
-   `gpl-sources.tar` asset.
+3. Each released version entry must contain the latest release tag and list
+   every expected wheel with the correct filename, SHA-256 hash, and
+   `Requires-Python` value. An entry with neither `tag` nor `files` is still
+   pending and will be built again by the next push touching the package. If
+   the package linked against one or more GPL-licensed projects, the same
+   version entry must also record its `gpl-sources.tar` asset.
 4. `patched: true` should be added if one or more patches are applied to the
    source for each version. If omitted, it defaults to `false`. This will
    produce a link to the appropriate patches
@@ -99,16 +103,13 @@ following workflows beyond those used for specific package builds:
    MERGE' tags are included in the subject lines, since commits of this type may
    be used for testing but should never be valid for merge. It also ensures that
    a valid `Upstream-Status` tag is included in every custom patch we include
-   when deviating from upstream packages' workflow/source checkouts.
-4. `pr-trigger.yml`: Provides a supplemental trigger mechanism for contributors,
-   allowing additional workflow runs for one or more packages to be triggered
-   with a PR by specifying the `Trigger: <package>:<version>` directive in the
-   PR description. This is only necessary if the default version in a workflow
-   is not the only one to be built, or if other maintenance-style changes are
-   being made where the contributors would like to validate behaviour. Note
-   this only works for workflows already registered on GitHub (i.e. already
-   merged to `main`, or having produced at least one `pull_request` run — see
-   above).
+   when deviating from upstream packages' workflow/source checkouts, and that
+   every changed `docs/packages/*.yaml` is well-formed and every changed
+   build workflow has one.
+4. `_setup.yml`: Called first by every `build-<package>.yml`; reads
+   `docs/packages/<package>.yaml` and outputs the versions to build (the
+   pending ones, or those matching the `version` glob of a
+   `workflow_dispatch`).
 
 ## The RISC-V Wheels Dashboard