SEP-1212: Split release CI into prep + rc1 steps for pre-RC1 internal QA day (#760)

## Summary

Split the `Release` GitHub Actions workflow into two dispatches so the
GAS team can validate a SHA-tagged internal-registry image during a
1-day internal QA window before `rc1` publishes to Docker Hub.

- **New `release_type: prep`** (Day 27) — `cmd_prep` + `make
release-prep` create `release/vX.Y.Z` from main HEAD, fire the rule #16
Jira version-create webhook, open the `main → vX.Y+1.0.dev0` dev-bump
PR, build the wheel, and trigger Jenkins with `pushImageDocker=false`
(SHA-tagged internal-registry image only). No version bump, no tag.
- **`cmd_rc(RC=1)` made idempotent against a prior prep** — probes
`origin` for the existing release branch and switches into an after-prep
path: syncs non-destructively to `origin/{branch}` (refuses to reset
when local is ahead), re-fires the rule #16 webhook (rule is naturally
idempotent), and gates the dev-bump PR call on `origin/main`'s actual
`pyproject.toml` version. The fresh-from-main path is bit-for-bit
unchanged (AC #6).
- **`make trigger-jenkins` parameterised** with `PUSH_IMAGE_DOCKER`
(default `true`). Deviation from the AC's literal wording
(`trigger-jenkins-internal SHA=<sha>` or `MODE=internal`): chose this
variable-on-existing-target approach as a finer-grained third path.
Pre-approved in the implementation plan.
- **Workflow YAML** adds `prep` to the choices, validates `rc_number`
must be empty for prep, and dispatches to `make release-prep`.
- 22 new unit tests cover `cmd_prep` happy path + preconditions +
ordering + head-sha → Jenkins, `cmd_rc` after-prep idempotency (webhook
re-fire, dev-bump skip-when-main-bumped, error-when-PR-unmerged,
non-destructive sync, refuse-when-local-ahead,
abort-on-rev-list-failure, still-bumps-and-tags),
`_remote_branch_exists` exit-code switch (0 / 2 / 128), and `prep`
argparse plumbing.

The workflow doc (release-process.md) is documented separately and
synced to Notion — the file is gitignored locally and does not ship in
this PR.

## Tested

- [ ] N/A — pure CI tooling. Tested via `pytest
tests/scripts/test_release.py -v` (57 tests pass), `make -n release-prep
VERSION=0.99.0`, `make -n trigger-jenkins TAG=abc
PUSH_IMAGE_DOCKER=false`, and `python3 scripts/release.py --help`. The
real integration test is the next release cycle's Day 27 dispatch by the
release manager.

## Checklist

- [x] New/modified functions have type hints and rST docstrings
- [x] New tests added for new features or bug fixes
- [x] ~~Database migrations generated if models changed (`make
makemigrations`)~~ *(N/A — no model changes)*
- [x] ~~User-facing changes documented (README, inline help, UI text)~~
*(N/A — release process change, documented in the workflow doc)*
- [x] Configuration changes documented with examples

Author: yyyyyyyan

.github/workflows/release.yml

@@ -8,14 +8,15 @@ on:
         required: true
         type: choice
         options:
+          - prep
           - rc
           - stable
       version:
         description: "Version number (e.g. 0.11.0)"
         required: true
         type: string
       rc_number:
-        description: "RC number (e.g. 1) — required for RC releases"
+        description: "RC number (e.g. 1) — required for RC releases, must be empty for prep"
         required: false
         type: string
 
@@ -54,6 +55,10 @@ jobs:
               exit 1
             fi
           fi
+          if [ "$RELEASE_TYPE" = "prep" ] && [ -n "$RC_NUMBER" ]; then
+            echo "::error::rc_number must be empty when release_type is 'prep'"
+            exit 1
+          fi
 
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
@@ -81,6 +86,8 @@ jobs:
         run: |
           if [ "$RELEASE_TYPE" = "rc" ]; then
             make release-rc VERSION="$VERSION" RC="$RC_NUMBER" SIGN_VIA_API=1
+          elif [ "$RELEASE_TYPE" = "prep" ]; then
+            make release-prep VERSION="$VERSION" SIGN_VIA_API=1
           else
             make release-stable VERSION="$VERSION" SIGN_VIA_API=1
           fi

Makefile

@@ -176,6 +176,13 @@ changelog-list:
 	@$(PYTHON) scripts/changelog.py list
 
 SIGN_FLAG := $(if $(SIGN_VIA_API),--sign-via-github-api,)
+PUSH_IMAGE_DOCKER ?= true
+
+release-prep:
+ifndef VERSION
+	$(error VERSION is required. Usage: make release-prep VERSION=X.Y.Z)
+endif
+	@$(PYTHON) scripts/release.py prep --version "$(VERSION)" $(SIGN_FLAG)
 
 release-rc:
 ifndef VERSION
@@ -194,7 +201,7 @@ endif
 
 trigger-jenkins:
 ifndef TAG
-	$(error TAG is required. Usage: make trigger-jenkins TAG=vX.Y.Z [WEBHOOK_URL_ENV=... WEBHOOK_AUTH_ENV=...])
+	$(error TAG is required. Usage: make trigger-jenkins TAG=vX.Y.Z [PUSH_IMAGE_DOCKER=false] [WEBHOOK_URL_ENV=... WEBHOOK_AUTH_ENV=...])
 endif
 	@set -euo pipefail; \
 	if [ -n "$${JENKINS_URL:-}" ] && [ -n "$${JENKINS_USER:-}" ] && [ -n "$${JENKINS_API_TOKEN:-}" ]; then \
@@ -204,7 +211,7 @@ endif
 			--data-urlencode "releaseTag=$(TAG)" \
 			--data-urlencode "notifySlack=true" \
 			--data-urlencode "pushImage=true" \
-			--data-urlencode "pushImageDocker=true" 2>&1; then \
+			--data-urlencode "pushImageDocker=$(PUSH_IMAGE_DOCKER)" 2>&1; then \
 			echo "    Jenkins build triggered successfully."; \
 			if [ -n "$(WEBHOOK_URL_ENV)" ] && [ -n "$(WEBHOOK_AUTH_ENV)" ]; then \
 				$(PYTHON) scripts/post_jira_webhook.py \
@@ -219,4 +226,4 @@ endif
 		echo "Note: JENKINS_URL/JENKINS_USER/JENKINS_API_TOKEN not all set, skipping Jenkins trigger."; \
 	fi
 
-.PHONY: venv build pack builder image format ruff djlint lint audit run-pre-commit dev-backend dev-frontend pip-audit bandit makemigrations makemigrations-plugin migrate checkmigrations test release-rc release-stable trigger-jenkins changelog-add changelog-check changelog-list
+.PHONY: venv build pack builder image format ruff djlint lint audit run-pre-commit dev-backend dev-frontend pip-audit bandit makemigrations makemigrations-plugin migrate checkmigrations test release-prep release-rc release-stable trigger-jenkins changelog-add changelog-check changelog-list