53. Releases cut from tags, one release branch per minor
Date: 2026-10-21
Status
Accepted
Context
bikesched had only snapshots of main on GitHub Packages (ADR 0015). The first release needs a
repeatable process: a version that cannot be mistyped, patches for a released version while main
moves on, a changelog of every change between two versions, and docs that show the version a
reader can actually use.
Considered for the process: release-please (a standing release PR that commits version and
changelog, but decides the version from the commits and has no Gradle support), Release Drafter
and GitHub’s generated release notes (both only see pull requests, while many commits are pushed
to main directly), git-cliff, and JReleaser. For branches: a release branch per minor, per major
(1.x), or created only when a patch is needed. For the version: tag-based Gradle plugins (axion,
reckon) or bump plugins (gradle-release), which either move the version out of the version catalog
or commit and tag themselves.
Decision
mainalways holds the next minor as a snapshot ingradle/libs.versions.toml(0.2.0-SNAPSHOT). A manual workflow (.github/workflows/release.yml) cuts releases: major or minor frommain, patch fromrelease/X.Y.x. The version is derived from the catalog by the Gradle taskreleaseVersions(jsemver, inbuild-logic), the build gets it as-PreleaseVersion; there is no release commit. The workflow tags the built commitvX.Y.Z.- A major or minor release creates its maintenance branch
release/X.Y.xfrom the tag, atX.Y.1-SNAPSHOT; only the latest minor gets patches. A branch per major (N.x) is added only oncemainworks on the next major whileN.yminors still ship. - Releases and snapshots are published to GitHub Packages for now; Maven Central comes later.
- JReleaser (Gradle plugin, configured in
bikesched.release) creates the GitHub Release with a changelog generated from the Conventional Commits since the previous release of the line, breaking changes first; build, CI, test, chore, refactoring and style commits are left out. The GitHub Releases are the only changelog: noCHANGELOG.mdin the repository, so a patch needs no commit onmain. A pull request title check keeps squash-merged commits conventional. - After a release the workflow commits the version bumps directly: dependency snippets in
README.mdanddocs/show the version of their branch (the release onrelease/X.Y.x, the snapshot onmain), so the website can show the latest release and the snapshot under/next/. - From the first release on, the database schema changes only through new migrations
(
V002__…), also in a breaking 0.x minor: users have data in the released schema.
Consequences
- Releasing is one click per release with a dry run that shows the version and the changelog; the
releaseenvironment can require an approval before anything is published. - JReleaser’s Gradle plugin needs JGit 5, while Spotless brings JGit 7 onto the same plugin
classpath.
build-logicexcludes JGit from Spotless, which only needs it to read line endings from.gitattributes; Spotless uses fixed LF line endings instead (the repository has no.gitattributes, and all sources use LF). - The workflow pushes with a deploy key (secret
RELEASE_DEPLOY_KEYin thereleaseenvironment), which the rulesets protectingmain,release/**andv*tags list as a bypass actor;GITHUB_TOKENcannot bypass rulesets. UnlikeGITHUB_TOKENpushes, its pushes start workflows, so the version bumps start the snapshot builds and the website deploy. - Fixes land on
mainfirst and are cherry-picked to the release branch. - Moving to Maven Central later adds signing and a JReleaser deployer to the same workflow.