0008 — A story lands on the base branch; a release is made there
Status: accepted (amends 0006 while maturity.flow exists; supersedes 0005 and 0007 when #199 removes the batch)
Date: 2026-11-13
Story: stories/032-tp-story-land-puts-a-story-in-a-pull-request-into.md
Context
At code level 1 a story reaches the base branch only as part of a
release. That one coupling is why release collects stories (0005),
why a lone story carries release commits and a second story has to undo
them (0007), and why tp release query exists to say which of those
states a checkout is in. The agents doing the stories lose their place
in it.
Trunk-based development names the
shape: release receives work before the trunk does and is merged into
it, where the site's release branch is cut from the trunk, takes only
cherry-picks from it and is never merged back. It keeps integrating and
releasing apart: short-lived branches merge to the trunk one at a time,
the trunk stays releasable, and a release is made from it.
The fragments already let stories be prepared in parallel without
touching a shared file, so nothing about the CHANGELOG needs release.
Options
How a release is made once stories merge to the base on their own, the base branch refusing direct pushes:
| Option | Complexity | Testability | Domain clarity | Operational risk |
|---|---|---|---|---|
A. tp release on the base gathers changes/ into a release/vX.Y.Z pull request, merges it and tags the merge |
0001's shape; the batch code goes | real git in a temp dir, a fake forge | a story lands, a release is one generated commit | a story that lands mid-release leaves its fragment for the next version: refuse to tag while fragments remain |
| B. The tag is the release; the CHANGELOG is rendered from fragments and tags | a renderer; README version markers need another home | parsing tests | the purest release from trunk | no committed CHANGELOG.md, against the project convention |
| C. tp pushes the release commit through a protection allow-list | a bypass per forge | needs a forge | protection becomes "except tp" | rejected in 0007 |
| D. Keep the batch | none | as today | integrating and releasing stay one act | the states 0007 added, and their cost to agents, stay |
How it is introduced:
| Option | Complexity | Domain clarity | Operational risk |
|---|---|---|---|
| R. Redefine code level 1 in one release | one large story | one fact picks the process | every level 1 project changes on upgrade; tp releases itself with the process it is replacing |
| N. A new code level | a rung beside batch | the ladder orders gates; this is not a stricter gate than batch | projects pass through a level they do not want (0006's objection to its option B) |
K. A temporary maturity.flow: trunk beside the batch, then R |
two processes in the tree for a few releases | a second fact, declared, with a removal story | the key outlives its purpose: #199 removes it |
Decision
A and K. Under maturity.flow: trunk at code level 1 and up a story
lands with tp story land, which merges the base in, checks, pushes and
opens the pull request into the base, and decides no version; tp release runs on the base branch only (#197). Each story of the epic
ships in a batch release with the new process unreachable unless the
key is set: branch by abstraction, the key the switch. When it has been
used on task-plus and one other project, #199 makes it what code level 1
means and deletes the batch and the key.
The ladder then orders how work reaches the trunk, which is what the site's styles order: 0 commits to it, 1 a story pull request, 2 the same with CI required. A release is the same act at every level.
Unfinished work that must merge is kept out of reach by not wiring it in, or by a declared key such as this one; tp provides no flag framework.
Consequences
Easier:
- A story's run has one outcome, an open pull request, and never reads release state. Stories are started and landed independently; a conflict between two shows when the later one merges the base in, in its own checkout.
- A batch needs no opening: a release holds whatever has landed since
the last tag.
.tp-release.yml,after:, the conversion and the unprepare have no counterpart.
Harder:
- The base branch carries merged work that is not released, so it must be releasable at every merge.
- Which finished stories a release holds is no longer chosen, except by not merging one.
- Until #199
maturity.codealone does not name the process, which 0006 set out to guarantee.
What still holds:
- 0005's fragments: the CHANGELOG line per story, the version from their kinds, the issues a release closes from their names.
- 0001's release pull request with the forge as the state, and 0003's bounded wait, for #197.
- 0006: the base branch is protected from code level 1.