| name | release-management |
| description | Prepares a MockServer release by recommending the release version from Semantic Versioning rules and `changelog.md`, checking release readiness, and listing the exact Buildkite release parameters. Use when users say "prepare release", "release version", "run the release pipeline", "which version should we release", or need to verify changelog and secret readiness before triggering the release pipeline.
|
Prepare a MockServer Release
Use this workflow before triggering the mockserver-release Buildkite pipeline.
Required Inputs
Inspect these sources every time:
changelog.md — especially the ## [Unreleased] sectionmockserver/pom.xml — current development -SNAPSHOT version.buildkite/release-pipeline.yml — supported release parameters and automated stepsdocs/operations/release-process.md — operator-facing release guidance- Git tags matching
mockserver-X.Y.Z — latest numeric release is the authoritative old-version
If AWS access is available, also verify the required secrets exist and contain the expected keys without printing secret values.
Version Recommendation Rules
Recommend the next release from the latest numeric mockserver-X.Y.Z tag, not from the current -SNAPSHOT alone.
Apply these rules in order:
- Major release — if any unreleased changelog bullet is explicitly marked
BREAKING:
- Minor release — if there are meaningful bullets under
Added or Changed and no BREAKING: markers
- Patch release — if there are only meaningful bullets under
Fixed
- Block release — if the unreleased changelog is empty, vague, or not ready to publish
Definitions:
- A "meaningful bullet" is a non-empty
- ... entry
BREAKING: should appear at the start of an unreleased bullet when a major version bump is intended
Derived values:
release-version: recommended SemVer releasenext-version: release-version patch increment plus -SNAPSHOTold-version: latest numeric mockserver-X.Y.Z tagrelease-type: full unless the user explicitly wants a partial reruncreate-versioned-site: yes for major or minor releases, no for patch releases
Readiness Checks
Validate each of these before declaring the release ready:
changelog.md has meaningful unreleased bulletschangelog.md does not already contain a section for the proposed release-versionmockserver/pom.xml is currently on an X.Y.Z-SNAPSHOT version- The pipeline supports the required outputs for this release:
- Maven Central core artifacts
mockserver-maven-plugin- Docker Hub and AWS ECR Public images
mockserver-nodemockserver-client- Helm
- Javadoc
- SwaggerHub / OpenAPI
- website
- JSON Schema
- PyPI
- RubyGems
- GitHub Release
- Required secrets are present:
mockserver-build/sonatypemockserver-build/dockerhubmockserver-build/pypimockserver-build/rubygemsmockserver-release/gpg-keymockserver-release/github-tokenmockserver-release/totp-seedmockserver-release/npm-tokenmockserver-release/swaggerhubmockserver-release/website-role
Output Format
Return a concise release-preparation report with these sections:
Recommendation
release-versionnext-versionold-versionrelease-typecreate-versioned-site
Rationale
- Explain why the bump is major, minor, or patch
- Cite the relevant changelog bullets and release tag comparison
Readiness
changelog: pass/fail with reasonversion state: pass/fail with current snapshot versionsecrets: pass/fail with missing items, if anypipeline coverage: pass/fail with any remaining gaps
Manual Follow-up
Steps outside — or not guaranteed by — the automated pipeline:
-
Homebrew — not a manual step; do not report it as one. Both formulae publish
automatically and need no action:
Homebrew/homebrew-core (mockserver, JAR-based) is bumped by BrewTestBot from the
*-brew-tar.tar artifact on Maven Central, typically within a few hours
(docs/operations/release-process.md §9).mock-server/homebrew-tap (self-contained bundle) is pushed by the pipeline's own
homebrew step (§11).
Only intervene if BrewTestBot has not opened a PR a day or two after release — §9 lists what
to check, and brew bump-formula-pr --strict --version=<release-version> mockserver is the
fallback for a broken bot, not the normal path.
-
SwaggerHub — the swaggerhub pipeline step is soft_fail: true, so a failure
never blocks the release. Publishing via the SwaggerHub Registry API needs
account / API-plan access the pipeline cannot guarantee — the write endpoint can
return 403/404 even with a valid key on an account without it. The step is kept
in the pipeline so it publishes automatically if that access is ever in place; but
if it soft-fails, upload the spec manually: open https://app.swaggerhub.com, go to
the jamesdbloom/mock-server-openapi API, and add the new version from
mockserver/mockserver-core/src/main/resources/org/mockserver/openapi/mock-server-openapi-embedded-model.yaml
(the web UI needs no API key). This may become fully automatic if SwaggerHub
changes that API behaviour.
Monitor & Verify
Always include this section verbatim so the operator can watch the release land. Substitute the chosen release-version into the URLs:
Notes
- Prefer explicit evidence from the repo over assumptions
- If the changelog suggests a major bump but no
BREAKING: marker exists, call that out and ask the user whether the release should be treated as breaking before finalising the recommendation
- If the user asks to run a partial rerun, keep
release-version and old-version consistent with the already-published release and explain which downstream steps will be skipped
