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>
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
devis the integration branch. Every change to the template lands there first. A commit ondevnever changesVERSIONor adds a changelog row.- A version is made by merging
dev. Mergingdevintoexperimental,testormainbumpsVERSIONand 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. - Paths.
dev→experimental→test→main,dev→test→main, ordev→main. A version keeps its number while it is promoted; promotion never bumps it again. - After a release,
mainis merged back intodev,testandexperimental, sodevstarts from the released version and no channel is ever behind the stable one. 1.xstays as it is: the maintenance line for 1.x, with fixes committed and numbered on it directly.devis not a channel.ckb-upgradecomparesVERSION, whichdevnever moves, so a KB ondevwould never see an upgrade. Asked fordev,ckb-initandckb-upgradeofferexperimental.
Consequences
- Merging
devtakes everything on it. A directdev→mainmerge is right only when all ofdevis ready to ship; otherwise go throughexperimentalortest. - Versions can be cut on
experimentalortestbeforemainsees them, so a KB on those channels can be ahead ofmain;ckb-upgradealready reports that as ahead, not current. - Two changes merged from
devat different times can't share a number, because the second merge always starts from the first'sVERSION.
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
deva channel too. Rejected: without version changes on it, an upgrade could never tell a KB ondevthat 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