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.