From 7c68721bb8ae4b9cfee71aad9439bc87413ad53d Mon Sep 17 00:00:00 2001 From: gwr0-0 Date: Sun, 11 Oct 2026 01:31:29 +0800 Subject: [PATCH] build: make the release pipeline rehearsable and recoverable The release job ran the test suite before release:prepare and then deployed a build that had never been verified, its dry run executed nothing at all, and a failure after release:prepare had no way back. - Gate the release job on tests passing so a release can no longer start from red code, and keep the suite running inside release:prepare as well: its forked "clean verify" is what stops a bad release before the tag is pushed. The suite therefore runs twice by design, in the Test job and in release:prepare; the previous comment claimed once. - Give the release job the Central credentials at job level. They were set on the single release step before, and setup-java resolves them from the environment, so splitting that step must not be allowed to drop them. - Run release:prepare and release:perform as two Maven invocations inside the publish step. The plugin's arguments parameter reaches both the prepare-time verify and the perform deploy through the phase they share, so -Darguments only applies to the invocation carrying it: the prepare-time verify runs the suite and only the deploy skips it. Omitting it on the perform invocation would run the suite again inside the deploy, because the perform mojo overwrites the stored exec.additionalArguments with its own value. The split is also what lets the recovery step run at all, since it is reached only if the publish step fails. - Make dryRun a real rehearsal: run release:prepare alone with dryRun and pushChanges disabled, drop the release:perform that executed no goals, and clean up without -DdryRun (release:clean has no such parameter, so the flag would be silently ignored). Rehearsal and cleanup share one step so the cleanup always runs and no message can report a failed rehearsal as OK. - Make the preflight fail closed. It refuses a tag or a Central version that already exists before anything is pushed, and a Central request that fails stops the run rather than being read as "the version is free" - the one case where the check must not pass. The version check also applies to rehearsals, so a rehearsal needs an unused version. - Pass workflow inputs to the shell through env instead of interpolating them into the script text. - Document the procedure, the limits of a rehearsal and the recovery steps in .github/workflows/RELEASING.md. The root POM no longer declares a (#3430); the new RELEASING.md assumes that change. --- .github/workflows/RELEASING.md | 108 +++++++++++++++ .github/workflows/release.yml | 234 +++++++++++++++++++++++++++++---- CONTRIBUTING.adoc | 5 + 3 files changed, 321 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/RELEASING.md diff --git a/.github/workflows/RELEASING.md b/.github/workflows/RELEASING.md new file mode 100644 index 0000000000..822d47f824 --- /dev/null +++ b/.github/workflows/RELEASING.md @@ -0,0 +1,108 @@ +# Releasing springdoc-openapi + +The release itself is driven by [`.github/workflows/release.yml`](release.yml), run from the branch +being released (`main` or `spring-boot-3`) with **Actions → Release → Run workflow**. +`spring-boot-3` predates the MCP modules, so the npm and dashboard steps are no-ops on that branch. + +The workflow must run in the canonical `springdoc/springdoc-openapi` repository, not a fork: +`release:prepare` pushes to the `` connection URL, while the preflight and the recovery step +check `origin`; the two agree only when `origin` names the same repository as ``. + +| Input | Example | Notes | +| -------------------- | --------------- | ---------------------------------------------------- | +| `releaseVersion` | `3.1.1` | Must not exist as a tag or on Maven Central already. | +| `developmentVersion` | `3.1.2-SNAPSHOT`| Version the release branch keeps afterwards. | +| `dryRun` | `false` | `true` rehearses `release:prepare` and changes nothing on the remote. | + +## What a real run does + +1. **Test job** — `./mvnw -Pci -T1C test`. Gates the release job, so a release never starts from red code. +2. **Preflight** — refuses a `releaseVersion` whose tag is already on `origin` or whose artifacts are + already published to Maven Central. Central releases are immutable, so this failure has to happen + before anything is pushed. It fails closed: if Central cannot be reached the run stops rather than + assume the version is free. + The check is not conditional on `dryRun`, so **a rehearsal needs an unused version** — rehearse the + next patch version, not one that is already out. That is also the version you would release, so a + rehearsal is worth running with the real candidate. +3. **`release:prepare`** — transforms the POMs to `releaseVersion`, runs its default + `preparationGoals` (`clean verify`, i.e. the full test suite **on the release POM**, hence the + second run of the suite in this workflow), commits, tags `v`, commits + `developmentVersion` and **pushes both commits and the tag**. + `release:perform` runs as a separate step, so it only starts once the tag actually exists. +4. **`release:perform`** — checks out the tag into `target/checkout` and runs `deploy` there with + `-DskipTests -Dskip.npm=false` (the suite already ran in step 3, and the MCP dashboard must still be + built from the tagged sources). Deployment goes to the Central Portal through + `central-publishing-maven-plugin`, which bundles and uploads the modules — including the parent + POM `org.springdoc:springdoc-openapi` — except `springdoc-openapi-tests` + (`true`), signs with the `gpg` profile and waits for validation + (`autoPublish=true`, `waitUntil=published`). + +Once a version is on Central it is immutable: it can never be overwritten or deleted, which is why +the preflight refuses a version that is already there. + +There is deliberately no `` in `pom.xml`: the Central plugin uses +`publishingServerId` against the Portal API, and a plain `` URL there would be ignored +while a `` element would silently turn `deploy` into `deploy site-deploy` in step 4. + +## Rehearsing + +Run with `dryRun: true` and a `releaseVersion` that is not published yet (see the preflight above). +That executes `release:prepare -DdryRun=true -DpushChanges=false`, which writes the bumped POMs next +to the originals and prints the SCM operations instead of committing them, then restores the working +tree and fails the run if anything is left dirty. It is a full trial of step 3 (which is where the +version bugs live). It cannot trial step 4, because `release:perform -DdryRun=true` intentionally +executes no goals at all. + +Step 4 is therefore rehearsed separately, by the `Snapshot` workflow: it deploys the same modules +with the same profiles, credentials and plugin through `./mvnw deploy` on every push to a release +line. A broken deploy configuration shows up there, not in a release run. + +## Recovering a failed release + +`release:prepare` puts the tag and both commits on the remote *before* `release:perform` runs, and +the Maven Release Plugin has no transaction covering the two. When a run fails, its last step +publishes which of the two cases you are in to the run summary. + +### Case A — failed before the tag was pushed + +Nothing reached `origin`. `release.properties` exists only in the runner, which is discarded, so: + +1. Fix the cause (dependency resolution, a flaky test, the GPG key, …). +2. Re-run the workflow with the same versions. `release:prepare` resumes by default (`resume=true`). + +### Case B — failed after the tag was pushed + +The tag `v` and both version-bump commits are on `origin`. `release:perform` may have +uploaded nothing, or uploaded a bundle that is still being validated on the Portal. Nothing is rolled +back automatically, and re-running with the same `releaseVersion` fails the preflight by design. + +1. **Check what Central actually received**: + . If the release is there — even only in + `validated` state — the release is effectively done: publish/drop it from the Portal and do not + re-run the workflow. +2. Otherwise, note the SHA of the failing run (`v`): + `git fetch origin --tags && git rev-parse 'refs/tags/v^{commit}'` +3. Undo the release on the maintenance branch, **only if nobody has pushed on top of it**: + `git push origin :refs/tags/v` and `git push --force-with-lease origin ^:`. + If in doubt, do not rewrite the branch — release a new patch version instead. +4. Re-run the workflow with the same versions. +5. If a version is beyond repair, bump the patch number (`3.1.2` instead of `3.1.1`) and delete the + half-finished tag so it cannot be mistaken for a real release. + +## Local equivalents + +Useful when diagnosing without touching the CI: + +```bash +# What the workflow runs for a real release: prepare first, so that perform only +# starts once the tag exists, then the deploy of that tag. +./mvnw -B -Pci,gpg release:prepare \ + -DreleaseVersion=3.1.1 -DdevelopmentVersion=3.1.2-SNAPSHOT +./mvnw -B -Pci,gpg release:perform -Darguments="-DskipTests -Dskip.npm=false" + +# Rehearsal, identical to dryRun: true +./mvnw -B -Pci,gpg release:prepare \ + -DreleaseVersion=3.1.1 -DdevelopmentVersion=3.1.2-SNAPSHOT \ + -DdryRun=true -DpushChanges=false +./mvnw -B -Pci,gpg release:clean # never pass -DdryRun here: release:clean has no such parameter +``` diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9f647f5fc0..ddad217fe1 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,5 +1,8 @@ # Cuts a release: tags it, publishes to Maven Central, bumps to the next SNAPSHOT. # Run it from the branch you want to release (main or spring-boot-3). +# +# The full procedure, including how to recover a failed release, is documented in +# .github/workflows/RELEASING.md. name: Release on: @@ -12,7 +15,7 @@ on: description: 'Next development version, e.g. 3.1.2-SNAPSHOT' required: true dryRun: - description: 'Rehearse only: no tag, no push, no publish' + description: 'Rehearse only: run release:prepare without committing, tagging or pushing' type: boolean default: false @@ -31,9 +34,51 @@ env: MAVEN_OPTS: -Xmx3g jobs: + # Releases on red code are the expensive mistake: release:prepare starts by + # bumping the POMs and only then verifies them. This job gates the release job. + test: + runs-on: ubuntu-latest + timeout-minutes: 30 + # This job only reads the checkout; keep the release job's write scope out of it. + permissions: + contents: read + steps: + - uses: actions/checkout@v7 + with: + fetch-depth: 1 + + - uses: actions/setup-java@v6 + with: + java-version: '21' + distribution: temurin + cache: maven + + # frontend-maven-plugin runs npm install for springdoc-openapi-starter-common-mcp. + - name: Cache npm + uses: actions/cache@v6 + with: + path: ~/.npm + key: npm-${{ hashFiles('**/src/main/frontend/package-lock.json') }} + restore-keys: npm- + + # -Pci keeps skip.npm=false; -T1C matches the runner's core count. + - name: Test + run: ./mvnw $MAVEN_ARGS -Pci -T1C test + release: + needs: test runs-on: ubuntu-latest - timeout-minutes: 90 + timeout-minutes: 120 + # Every Maven and git command below runs with these set. The release plugin + # forks a second Maven process, and setup-java writes the Central credentials + # into settings.xml as ${env.MAVEN_USERNAME}/${env.MAVEN_PASSWORD}, so both the + # outer and the forked build need them in the environment. Keeping them at job + # level means no step can lose them by accident. + env: + MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }} + MAVEN_PASSWORD: ${{ secrets.MAVEN_CENTRAL_TOKEN }} + MAVEN_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} steps: - uses: actions/checkout@v7 with: @@ -65,20 +110,126 @@ jobs: # uses an SSH URL, and release:perform clones it fresh into # target/checkout. The runner has no SSH key, so route it over HTTPS. git config --global url."https://x-access-token:${GITHUB_TOKEN}@github.com/".insteadOf 'git@github.com:' + + # release:prepare, not release:perform, is the step that puts something + # irreversible on the remote: it tags the release commit and pushes the tag + # and both version-bump commits, and only then can release:perform fail. + # Check the two cheap preconditions first so that a version which already + # exists is rejected before the release build even starts. + - name: Preflight + # The inputs reach the shell as environment variables, never interpolated + # into the script text, so a version string cannot inject shell syntax. env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + VERSION: ${{ inputs.releaseVersion }} + run: | + set -euo pipefail - # Tests run once, here. The release build itself uses -DskipTests so the - # suite is not executed a third time (release:prepare verifies, then - # release:perform builds again from the tag). - - name: Test - run: ./mvnw $MAVEN_ARGS -Pci -T1C test + if [ -n "$(git ls-remote --tags origin "refs/tags/v${VERSION}")" ]; then + echo "::error::Tag v${VERSION} already exists on origin. release:prepare would fail while tagging, leaving the repo half-versioned. Pick a new releaseVersion." + exit 1 + fi + + if git rev-parse -q --verify "refs/tags/v${VERSION}" >/dev/null; then + echo "::error::Tag v${VERSION} already exists in this checkout." + exit 1 + fi + + # A version that is already on Central is refused here, so a rehearsal + # cannot reuse a published version either: pick a version nobody has + # published, such as the next patch, to try the release out. + # + # This check fails closed. "Central is unreachable" must not be reported + # as "the version is free": the request is cheap, and the expensive + # mistake is the release that gets refused after prepare has already + # pushed the tag. The curl exit status and the HTTP status are both + # checked explicitly, so neither a DNS/TLS failure (curl's own exit + # status) nor an HTTP error such as a 404 can empty the version check. + METADATA="${RUNNER_TEMP}/springdoc-versions.xml" + METADATA_URL=https://repo1.maven.org/maven2/org/springdoc/springdoc-openapi-starter-common/maven-metadata.xml + + # `if` keeps `set -e` from aborting on a failed curl, so the diagnostic + # below is what the log shows instead of a bare curl error. + if HTTP_CODE=$(curl -sSL -o "${METADATA}" -w '%{http_code}' "${METADATA_URL}"); then + curl_status=0 + else + curl_status=$? + fi + + if [ "${curl_status}" -ne 0 ] || [ "${HTTP_CODE}" != "200" ]; then + echo "::error::Could not read the published versions of springdoc-openapi-starter-common from Maven Central (curl exit ${curl_status}, HTTP ${HTTP_CODE}). Re-run once the repository is reachable; the preflight cannot confirm that ${VERSION} is unused." + exit 1 + fi + + if grep -qF "${VERSION}" "${METADATA}"; then + echo "::error::springdoc-openapi ${VERSION} is already published to Maven Central and cannot be republished. Pick a new releaseVersion." + exit 1 + fi + + # The rehearsal and its cleanup share one step on purpose: release:prepare + # rewrites the POMs in place, so the cleanup has to run even when the + # rehearsal fails, and a later step cannot read an earlier step's status. + # Keeping both commands here also means no message can report a failed + # rehearsal as OK - the case the separate cleanup step got wrong. + - name: Rehearse release preparation + if: ${{ inputs.dryRun }} + env: + RELEASE_VERSION: ${{ inputs.releaseVersion }} + DEVELOPMENT_VERSION: ${{ inputs.developmentVersion }} + run: | + # The status of the rehearsal is captured rather than propagated, so the + # cleanup below always runs and the failure is reported at the end. + set +e - # -Pgpg is required, not optional: maven-release-plugin is declared inside - # the gpg profile, so without it the plugin falls back to the parent's - # pluginManagement version and none of its configuration applies — - # wrong tag name, no autoVersionSubmodules, and release:perform would - # deploy unsigned artifacts that Central rejects. + # -DpushChanges=false keeps the rehearsal local even if the dry-run flag + # ever stops suppressing commits; release:prepare then leaves the bumped + # POMs and release.properties behind for the cleanup below. + ./mvnw $MAVEN_ARGS -Pci,gpg release:prepare \ + -DreleaseVersion="${RELEASE_VERSION}" \ + -DdevelopmentVersion="${DEVELOPMENT_VERSION}" \ + -DdryRun=true \ + -DpushChanges=false + rehearsal_status=$? + + # release:clean restores the POMs from the .releaseBackup files and drops + # release.properties. It must not be given -DdryRun: the mojo has no such + # parameter, so the flag would be ignored while making the cleanup look + # like a dry run when it actually restores the tree for real. + # The git restore and the find below are the belt-and-braces equivalents, + # and they are what actually guarantees a clean tree: a failed + # release:clean must not stop them. + ./mvnw $MAVEN_ARGS -Pci,gpg release:clean + git checkout -- . + find . \( -name '*.releaseBackup' -o -name 'release.properties' \) -delete + + if [ -n "$(git status --porcelain)" ]; then + echo "::error::The rehearsal left changes in the working tree:" + git status --short + if [ "${rehearsal_status}" -ne 0 ]; then + echo "::error::release:prepare had already failed with exit code ${rehearsal_status}; the leftover files are secondary to that failure." + fi + exit 1 + fi + + if [ "${rehearsal_status}" -ne 0 ]; then + echo "::error::release:prepare failed with exit code ${rehearsal_status}. The working tree was restored; re-run with the same versions once the cause is fixed (release:prepare resumes by default)." + exit 1 + fi + + echo "Rehearsal OK: release:prepare completed and the working tree is clean again." + + # The tagged build is what gets published, so it is the build that has to + # pass. release:prepare runs its preparationGoals ("clean verify", the plugin + # default) on the transformed POM, which is why the suite runs a second time + # in this workflow: that forked verify is what turns red code into a stopped + # release rather than a pushed tag. The separate Test job exists to fail even + # earlier, before the version transformation starts. + # + # -Darguments is the release plugin's `arguments` parameter, and the shared + # phase that consumes it (AbstractRunGoalsPhase) feeds both the prepare-time + # verify and the perform-time deploy. While prepare and perform were a single + # command that parameter therefore skipped tests in both; now that perform is + # its own invocation, -Darguments applies only to the invocation that carries + # it, so the prepare-time verify runs the suite and only the deploy skips it. # # -Dskip.npm=false is forced for the same reason the profiles are explicit. The MCP # dashboard assets are build output and are no longer tracked in git, so a release @@ -86,19 +237,50 @@ jobs: # builds in its own target/checkout, where a workflow-level path check cannot gate the # deploy, so pin the property here and let the enforcer rule in # springdoc-openapi-starter-common-mcp fail the build if the assets are still missing. - - name: Release + - name: Prepare and publish + if: ${{ !inputs.dryRun }} + env: + RELEASE_VERSION: ${{ inputs.releaseVersion }} + DEVELOPMENT_VERSION: ${{ inputs.developmentVersion }} run: | - ./mvnw $MAVEN_ARGS -Pci,gpg release:prepare release:perform \ - -DreleaseVersion='${{ inputs.releaseVersion }}' \ - -DdevelopmentVersion='${{ inputs.developmentVersion }}' \ - -DdryRun=${{ inputs.dryRun }} \ - -Darguments="-DskipTests -Dskip.npm=false" + ./mvnw $MAVEN_ARGS -Pci,gpg release:prepare \ + -DreleaseVersion="${RELEASE_VERSION}" \ + -DdevelopmentVersion="${DEVELOPMENT_VERSION}" + + # release:perform deploys the tag that the step above pushed. It resolves + # its parameters from release.properties, so it takes no versions here - + # but it does need -Darguments, because the perform mojo overwrites the + # stored exec.additionalArguments with its own value: omitting it here + # would run the whole suite again inside the deploy. + ./mvnw $MAVEN_ARGS -Pci,gpg release:perform -Darguments="-DskipTests -Dskip.npm=false" + + # Publish, tag and version bump are three separate steps on the remote and + # Maven Release Plugin has no transaction across them, so the only thing + # this step can do is state exactly how far the run got. + - name: Say how to recover + if: ${{ failure() && !inputs.dryRun }} env: - MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }} - MAVEN_PASSWORD: ${{ secrets.MAVEN_CENTRAL_TOKEN }} - MAVEN_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + VERSION: ${{ inputs.releaseVersion }} + run: | + set -uo pipefail + TAG="v${VERSION}" - - name: Clean up a dry run - if: ${{ inputs.dryRun }} - run: ./mvnw $MAVEN_ARGS -Pci,gpg release:clean + if [ -n "$(git ls-remote --tags origin "refs/tags/${TAG}")" ]; then + { + echo "## Release ${VERSION} failed after the tag was pushed" + echo + echo "The tag \`${TAG}\` and both version-bump commits are on origin, but Central may" + echo "have received nothing or only part of the release. Nothing is rolled back" + echo "automatically and re-running this workflow will refuse to reuse the version." + echo + echo "Recovery steps: [.github/workflows/RELEASING.md](../blob/${GITHUB_REF_NAME}/.github/workflows/RELEASING.md)" + } >> "$GITHUB_STEP_SUMMARY" + else + { + echo "## Release ${VERSION} failed before the tag was pushed" + echo + echo "Nothing reached origin. release.properties may be in the working tree of this" + echo "runner only, and release:prepare resumes from it by default, so it is usually" + echo "enough to fix the cause and re-run this workflow with the same versions." + } >> "$GITHUB_STEP_SUMMARY" + fi diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 58ad3d80a3..c7ddd149c7 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -153,6 +153,11 @@ The release and snapshot builds always build the frontend (`-Pci`, and `-Dskip.n the release workflow), so published artifacts always carry a dashboard built from the sources they were tagged from. +== Releasing + +Cutting a release, rehearsing one, and recovering a failed one is documented in +link:.github/workflows/RELEASING.md[`.github/workflows/RELEASING.md`]. + == Cloning the git repository on Windows Some files in the git repository may exceed the Windows maximum file path (260 characters), depending on where you clone the repository.