032 — tp story land puts a story in a pull request into the base under maturity.flow trunk (#202)
Status: in progress Roadmap: #196
Why
At code level 1 a story reaches the base branch only as part of a
release: tp release on its branch either makes the release commits
there (a lone release) or sends it through release (a batch), and a
second story converts one into the other
(ADR 0007).
Whoever runs it, usually an agent, has to work out which of those states
the repository is in before every step, and the story's own run decides
a version it should know nothing about.
Trunk-based development keeps the two acts apart: a short-lived branch is integrated into the trunk when it is ready, and a release is made from the trunk later. This story is the first half, built beside the batch and chosen by a temporary key (ADR 0008), so it ships in an ordinary release without changing any project that has not asked for it.
Vocabulary
| Term | Meaning |
|---|---|
| land | put a story branch in a pull request into the base branch: base merged in, checks passed, pushed. No version, no release commits |
| trunk flow | code level 1 or 2 with maturity.flow: trunk: stories land; a release is made on the base branch |
| batch flow | code level 1 or 2 without the key: today's process |
What changes
task-plus.yml:maturity.flow, empty ortrunk. Any other value is a config error.trunkat code level 0 is a config error: level 0 commits to the base and has nothing to land.tp story land [-dry-run](new): on a story branch under trunk flow, merges the remote base branch into it when the base has moved, runs the checks, pushes and opens the pull request into the base branch, titled by the story's fragment. An open pull request is reused. The run ends there: the merge is the human's.tp releaseunder trunk flow refuses: on a story branch it namestp story land; on the base branch it says the release from the base is #197.docs/story.md,docs/maturity.md: the command and the key.
Acceptance
tp story land:
| Flow | Branch | State | Outcome |
|---|---|---|---|
| batch, or code 0 | any | any | error naming maturity.flow: trunk; nothing done |
| trunk | the base branch | any | error: land runs on a story branch |
| trunk | not story/<n>-<slug> |
any | error naming the form |
| trunk | story | working tree dirty | error; nothing done |
| trunk | story | release on the remote |
error: a batch is in flight, finish it first |
| trunk | story | no changes/<n>.<kind>.md |
error naming the file to add |
| trunk | story | CHANGELOG names an untagged version (a lone release's commits) | error: land takes no release commits |
| trunk | story | already in the base branch | says so; nothing pushed, no pull request |
| trunk | story | its last pull request closed without merging | error: reopen it or close the story |
| trunk | story | its pull request open into another branch | error: retarget or close it |
| trunk | story | level with the base | checks, push, pull request into the base titled by the fragment; CHANGELOG and fragment untouched; no tag |
| trunk | story | base has moved, merges cleanly | the remote base merged in, then as above |
| trunk | story | base has moved, conflicts | the merge is left in progress; error names the files; nothing pushed |
| trunk | story | checks fail | error; nothing pushed, no pull request |
| trunk | story | its pull request into the base open | checks, push; the pull request reused |
| trunk | story | -dry-run |
each step printed; nothing merged, pushed or opened |
tp release:
| Flow | Branch | Outcome |
|---|---|---|
| trunk | story | error naming tp story land |
| trunk | the base branch | error: the release from the base under trunk flow is #197 |
| batch | any | as today |
Out of scope
- The release from the base under trunk flow (#197) and
tp release query(#198). - Waiting for the merge:
merge_waitis not read bytp story land. - A worktree per story (#193).
- Removing the batch and the key (#199).
Decisions
Done when
- tests express the acceptance table and pass
- spec updated
- ADR written if a fork was resolved
- roadmap ticked and stamped; changelog entry
- issue closed with a link to the release