ADR 0022: Releases with Release Please, squash merges into develop and an install script
- Status: Accepted
- Date: 2026-11-03
Context
ADR 0016 computed the version with git-cliff from the tags and never committed it. After v0.2.0 was published, package.json still said 0.1.0. dak --version and the version that the MCP server announces read package.json, and the README installs from a clone, so every clone reported the wrong version. Only the release tarball carried the right one.
The same ADR merged every pull request with a merge commit, so each atomic commit of a branch reached the release notes. The notes of v0.2.0 list six lines for one feature (the metadata cache), and those of v0.1.0 list internal steps and fixes to code that was never released.
The maintainer wants the release flow to need as little intervention as possible.
Decision
This ADR supersedes the release workflow, the "version is not committed" rule and the "merge commits only" rule of ADR 0016. Everything else in ADR 0016 stays.
- Release Please replaces git-cliff. It runs in manifest mode (
release-please-config.json,.release-please-manifest.json, starting at0.2.0). On every push tomainit reads the Conventional Commits since the last tag. With a releasable commit (feat,fix,perfor a breaking change) it opens or updates a pull request that bumpsversioninpackage.jsonandpackage-lock.json. Merging that pull request creates the tagvX.Y.Zand the GitHub Release, and a second job ofrelease.ymlattaches the tarball andscripts/install.shto it. The version is now committed, so a clone, the tarball and the tag agree. - No changelog file.
skip-changelogkeepsCHANGELOG.mdout of the repository; GitHub Releases stays the changelog. The package stays private and is not published to npm. RELEASE_PLEASE_TOKEN. A fine-grained personal access token (this repository only,contentsandpull requestsin write mode, valid for one year) creates the release pull request and the sync pull request. Pull requests created withGITHUB_TOKENdo not start workflows, so the required checks would never run on them.- Squash into
develop, merge commit intomain. Pull requests intodevelopare squash-merged: the title of the pull request is the commit and the line in the release notes, and the atomic commits stay in the branch and on the pull request page. Thecommitscheck also validates the title with commitlint, and re-runs when the title is edited. Pull requests intomainkeep the merge commit. The promotion must not be squashed, because that would hide itsfeatandfixcommits from Release Please. mainstops requiring an up-to-date branch. With squash merges intodevelop,mainis never an ancestor ofdevelop, so a strictmainwould mark every promotion as out of date. The checks still run on the proposed merge result of each pull request.- Back-merge
mainintodevelopis automatic.sync.ymlruns on every push tomain.scripts/ci/sync-main-into-develop.shpushessync/main-into-develop(develop plus a merge ofmain) only when that would change the tree ofdevelop, and the workflow opens the pull request intodevelop. After the sync pull request is squash-merged, the trees agree and the next run opens nothing. A conflict fails the workflow. - Branch policy.
release-please--*branches are accepted intomain, andsync/*branches intodevelop. - Install script.
scripts/install.shchecks Node.js 22.18 and npm, resolves the latest release (orDAK_VERSION) and runsnpm install --globalon its tarball. It installs nothing else, uses nosudoand does not change the PATH. It is attached to every release, soreleases/latest/download/install.shalways serves the script of the latest release. The README documents two ways to install: cloning the repository and this script.
Consequences
- The maintainer merges three pull requests per release in the web UI, with the bypass: the promotion
developtomain, the release pull request and the sync pull request. The bot creates the last two with the maintainer's token, so the maintainer cannot approve them. - The token expires after a year and must be renewed. When it is missing or expired, the
ReleaseandSync developworkflows fail onmain. - The rulesets are GitHub settings, not files. After this change is merged,
protect-developallows only squash merges, andprotect-mainstops requiring an up-to-date branch. The maintainer applies them, as in ADR 0016. - The
workflow_dispatchdry run of the old release workflow is gone. The release pull request shows the next version and the notes before anything is published. - The commits of a feature branch no longer appear one by one in the history of
develop. Afix:commit inside a feature that is not released yet no longer appears in the notes either. Only the title of the pull request counts. - The release exists for a short time before the tarball and
install.share attached. An installation in that window fails and works if repeated. - Not verified before the first release on
main: that Release Please accepts its release pull request merged with a merge commit, and that the notes are published withoutCHANGELOG.md. If the first fails,mainwill also accept squash merges for that pull request only.