ckb/docs/decisions/0022-dev-branch-and-merge-versioning.md
Michał Kopeć 6722aa564b Branch flow: dev integration branch, version changes only on merge (D-0022)
All work lands on dev; VERSION and the changelog change only when dev is
merged into experimental, test or main. Paths: dev->experimental->test->main,
dev->test->main, dev->main. A version keeps its number when promoted; main
is merged back into dev, test and experimental after a release. 1.x keeps
its own fixes. experimental becomes the preview channel; dev is not a
channel, and ckb-init/ckb-upgrade offer experimental when asked for it.
README, manuals, changelog channel sections and D-0022 updated; Polish
manual gains the profile-skills section.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 12:09:25 +01:00

3.7 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision All template work lands on a `dev` integration branch; VERSION and the changelog change only when dev is merged into experimental, test or main (dev→experimental→test→main, dev→test→main, or dev→main), a version keeps its number when promoted, main is merged back into dev/test/experimental after a release, and 1.x keeps its own fixes; dev is not a channel. accepted 2026-11-12 Michał Kopeć AGENTS.md, README.md, README.pl.md, docs/MANUAL.md, docs/MANUAL.pl.md, docs/CHANGELOG.md, docs/CHANGELOG.pl.md, .agents/skills/ckb-upgrade/, .agents/skills/ckb-init/SKILL.md, VERSION 0.85 0.8 2026-11-12 365 high

D-0022 — Work lands on dev; the version changes only when dev is merged

Status: Accepted · Decided: 2026-11-12 · Deciders: Michał Kopeć

Context

Until 2.2.0 every change was committed straight to main with its own version bump, and test and experimental were never updated after they were created: on 2026-11-12 both still pointed at the 1.9.0 commit, 27 commits behind main. A KB switched to either channel would have received older tooling than the stable one. Work in progress also had nowhere to live without being released.

Decision

  1. dev is the integration branch. Every change to the template lands there first. A commit on dev never changes VERSION or adds a changelog row.
  2. A version is made by merging dev. Merging dev into experimental, test or main bumps VERSION and adds the changelog row in the merge commit. The number follows the existing rule: major for breaking changes or significant architecture changes, minor for new features, patch for fixes and documentation; the highest kind in the merge wins.
  3. Paths. dev → experimental → test → main, dev → test → main, or dev → main. A version keeps its number while it is promoted; promotion never bumps it again.
  4. After a release, main is merged back into dev, test and experimental, so dev starts from the released version and no channel is ever behind the stable one.
  5. 1.x stays as it is: the maintenance line for 1.x, with fixes committed and numbered on it directly.
  6. dev is not a channel. ckb-upgrade compares VERSION, which dev never moves, so a KB on dev would never see an upgrade. Asked for dev, ckb-init and ckb-upgrade offer experimental.

Consequences

  • Merging dev takes everything on it. A direct dev → main merge is right only when all of dev is ready to ship; otherwise go through experimental or test.
  • Versions can be cut on experimental or test before main sees them, so a KB on those channels can be ahead of main; ckb-upgrade already reports that as ahead, not current.
  • Two changes merged from dev at different times can't share a number, because the second merge always starts from the first's VERSION.

Alternatives considered

  • Bump on every commit (the old practice). Rejected: it leaves no place for unfinished work and no reason to keep the pre-release channels moving.
  • Make dev a channel too. Rejected: without version changes on it, an upgrade could never tell a KB on dev that anything had changed.

Evidence

change the branch structure ... keep 1.X.X branch for fixing, create a experimental, dev and test branches, version is changed only when dev is merged to any other branch. The typical merging path will be dev->experimental->test->main or dev->test->main or dev->main major, minor, and breaking changes versioning stays as it is

— Chat conversation, Michał Kopeć, 2026-11-12