033 — tp release on the base under trunk flow releases what has landed (#204)

Status: in progress Roadmap: #197

Why

Under maturity.flow: trunk a story lands on the base branch with tp story land (story 032) and tp release refuses, so a project that sets the key cannot release. This story is the other half of ADR 0008: the release is one run on the base branch, of whatever has landed since the last tag, with no list of stories and no release branch to open.

The base branch refuses direct pushes, so the release commits reach it by a pull request that holds nothing else. It is generated, so tp merges it itself: the human's act is running tp release and confirming its plan.

Vocabulary

Term Meaning
landed on the base branch, merged from a story's pull request; its fragment is in changes/ there
release pull request release/vX.Y.Z into the base branch, holding only the release commits
redo a release pull request that reverts the release commits of an untagged version and makes them again over every fragment now landed

What changes

  • tp release on the base branch under trunk flow: cuts release/vX.Y.Z from the remote base, makes the release commits there (the fragments on the base gathered, the version from their kinds), runs the checks, pushes, opens the pull request Release vX.Y.Z into the base, merges it through the forge, then tags and publishes the base branch as a batch's tag run does. The issues the fragments name are closed and release/vX.Y.Z deleted after the tag.
  • A forge that refuses the merge (approvals, a check pending) leaves the pull request open with the reason printed; with merge_wait the run waits for a human to merge it and then tags.
  • A version is not tagged while fragments remain on the base branch: a story that landed between the release pull request's cut and the tag would ship without its CHANGELOG line. The run stops, and the next run is a redo.
  • Forge clients: a call to merge a pull request (Forgejo, GitLab).
  • docs/release-workflow.md, docs/maturity.md.

Acceptance

tp release on the base branch under trunk flow. "Untagged" is the remote base's CHANGELOG naming a version with no tag.

CHANGELOG Fragments on the base Release pull request Outcome
latest version tagged none none error: nothing has landed since the last tag
latest version tagged some none release commits on release/vX.Y.Z, checks, push, pull request, merged by tp, base tagged and published; issues closed; release/vX.Y.Z deleted
latest version tagged some none; the forge refuses the merge pull request left open, the reason printed, nothing tagged; with merge_wait the run waits for the merge and tags
latest version tagged some none; checks fail on the release commits error; nothing pushed, no pull request, back on the base branch
any any open from release/v… merged by tp, then the run starts again on the result
untagged X none none X tagged and published
untagged X some none redo: release/vY carries Unprepare vX and the release commits of Y over every fragment, Y not below X; then as the second row. X is never tagged
a story lands after the merge, before the tag error naming the fragments; nothing tagged; the next run is the row above
-dry-run some none each step printed; nothing cut, pushed, opened or merged

Out of scope

  • tp release query under trunk flow (#198).
  • Detecting a stale release pull request before merging it: the redo covers it after the merge.
  • Requiring pull requests to be up to date on the forge.
  • Deleting landed story branches: the forge's delete-on-merge, or the tidy line tp story land prints.

Decisions

ADR 0008, option A. The redo is forward-only, as 0007's conversion was: one revert commit, no force push.

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