From 311739df5694b41470409860a89e9e429c68a0ec Mon Sep 17 00:00:00 2001 From: Anurag Bandyopadhyay Date: Tue, 3 Nov 2026 20:17:59 +0530 Subject: [PATCH] chore: consolidate release guide into RELEASING.md --- RELEASE.md => RELEASING.md | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) rename RELEASE.md => RELEASING.md (71%) diff --git a/RELEASE.md b/RELEASING.md similarity index 71% rename from RELEASE.md rename to RELEASING.md index 772dbad0..91cddea3 100644 --- a/RELEASE.md +++ b/RELEASING.md @@ -24,11 +24,15 @@ routine breaking changes. 1. Go to **Actions → release-please** and click **Run workflow**. 2. Choose a bump type: + - `auto` — bump determined from the conventional commits since the last release (default) - `patch` — bugfixes, docs, small changes - `minor` — breaking changes (see above) - - `explicit` — you specify the exact version string (e.g. `0.10.0` or `0.10.0-beta.1`) + - `explicit` — uses the exact version entered in `release-version` (e.g. `0.10.0` or + `0.10.0-beta.1`); the other bump types ignore that field 3. The workflow creates a release PR. Review it, then merge. -4. The GitHub Release and tag are created automatically on merge. +4. On merge, CI pushes a signed `vX.Y.Z` tag and a draft GitHub release. The tag triggers + **Java CI with Gradle**, which publishes to Maven Central and GitHub Packages, then + undrafts the release. If the release stays a draft, check that run. > **Note — release-please only understands `auto` or an explicit version string.** > The `patch`, `minor`, and `major` options in the workflow dropdown are conveniences @@ -65,6 +69,9 @@ every beta, incrementing the suffix manually: 0.10.0-beta.1 → explicit: 0.10.0-beta.2 → explicit: 0.10.0 ``` +The `release-please-develop` pre-release lane is configured but needs a `develop` branch +first; until then, cut pre-releases from `main` with `explicit`. + --- ## What goes in the changelog @@ -77,10 +84,34 @@ feat: add support for batch check → Added fix: correct retry logic for transient errors → Fixed docs: update API reference → Documentation perf: cache DNS lookups → Changed -refactor: extract auth helper → (hidden) +refactor: extract auth helper → Changed chore: bump dependencies → (hidden) ``` +### Overriding a changelog entry + +If a commit message isn't user-facing, add this block to the PR description (before or +after merging; re-run the release workflow to pick it up). release-please uses it instead +of the commit message: + +``` +BEGIN_COMMIT_OVERRIDE +feat: user-facing description of the change +END_COMMIT_OVERRIDE +``` + +### Breaking changes + +Mark the type with `!` and add a `BREAKING CHANGE:` footer. PRs are squash-merged, and GitHub defaults the squash +title to the commit title for single-commit PRs (the PR title otherwise), so check that the final squash title has +the `!` and its body has the footer before merging: + +``` +feat!: remove the Foo option + +BREAKING CHANGE: the Foo option has been removed. Use Bar instead. +``` + --- ## Troubleshooting