A release pull request takes release-hold while it is finished (issue btclib-org/ai-agents-process#403)

.github/labels.yml

@@ -69,7 +69,9 @@ labels:
   - name: api-break
     color: "e99695"
     description: Breaks the public API; set by a job, advisory
-    repositories:
+    # the trees with a release.yml, whose RELEASING.md section 14 copies:
+    # tier 1, as the loop in README section 2 lists it
+    repositories: &publishing
       - btclib
       - btclib-secp256k1
       - bitcoin-core-rpc
@@ -81,6 +83,11 @@ labels:
       - bip32-descriptors
       - coin-addresses
       - seed-scan
+  - name: release-hold
+    color: "d876e3"
+    description: >-
+      A release under way; other merges here wait until it is published
+    repositories: *publishing
 
 # Labels the test passes over, neither owed nor refused.
 #

README.md

@@ -3701,6 +3701,8 @@ A label means what its description says. Who applies and removes it:
   wait, and removed by whoever finds it over;
 - `on-hold` — applied by whoever pauses the issue, and removed by
   whoever resumes it;
+- `release-hold` — applied and removed as `RELEASING.md`'s *Release to
+  PyPI* says;
 - `upstream-dependent` — applied by whoever finds the dependency, and
   removed by whoever finds the wait over;
 - `upstream-report` — applied by whoever finds the report owed. Once it

shared/RELEASING.md

@@ -480,6 +480,59 @@ request, next to `deps-latest`'s own result.
    pull request that never mentions it reads exactly like one that skipped
    it.
 
+1. Hold the repository's other merges until the release is published, so
+   that `main` does not move under the release between its gates and its
+   tag. Put `release-hold` on the release pull request:
+
+   ```shell
+   pr=<the release pull request's number>
+   ```
+
+   ```shell
+   gh pr edit "${pr:?}" --add-label release-hold
+   ```
+
+   While a pull request carries the label, nobody merges another pull
+   request into `main` here. A red `main`'s repair is the exception: it
+   goes first, as `CONTRIBUTING.md`'s *Landing it* says. A release pull
+   request waits only while a lower-numbered pull request carries the
+   label, so that releases go out oldest first instead of each waiting on
+   the others.
+
+   A pull request can merge between the version step and the label. So
+   once the label is on, fetch, and check that `origin/main` is still the
+   branch's base:
+
+   ```shell
+   git fetch origin
+   ```
+
+   ```shell
+   git merge-base --is-ancestor origin/main HEAD
+   ```
+
+   After a fetch that succeeded, where `merge-base` exits 1, `main` has
+   moved, and the branch is redone on it as the version step says, before
+   the gates. Any other non-zero exit, of either command, is an error to
+   read, not an answer.
+
+   An older release or a red `main`'s repair can still move `main` during
+   the hold. So both commands run again just before the merge, and where
+   `main` has moved, the branch is redone as the version step says, which
+   gates it again.
+
+   Remove the label once `release.yml`'s run on the tag has published the
+   release, or once the release is abandoned and its pull request closed:
+
+   ```shell
+   gh pr edit "${pr:?}" --remove-label release-hold
+   ```
+
+   A label left behind on a release already published or abandoned holds
+   every merge here. Whoever finds one checks that the release is out or
+   its pull request closed, tells the maintainer, and removes the label on
+   his word.
+
 1. Run `uv run pre-commit run --all-files` and `uv run pytest --cov`
    before pressing anything, then verify the Read the Docs build renders,
    on `https://app.readthedocs.org/projects/<rtd>/builds/`. Read the