024 — tp release query reports the release in progress (#96)
Status: shipped (v0.28.0)
Why
Before running tp release, you have to piece together what it is about
to do. That means git branch -r, the release branch's log,
.tp-release.yml, .tp-release-inflight and the forge's pull requests,
read side by side. With story 021's batches, and story 023's walk, more
stories are in play at once. The question "which stories are in this
release, which are still to merge, and what else is open" deserves one
command that answers it without changing anything.
Vocabulary
| Term | Meaning |
|---|---|
| last release | the newest version tag on the base branch |
| in the release | a story branch whose tip is an ancestor of the release line: release when fragments: true, else the base branch since the last release |
| listed | named in .tp-release.yml stories: and not yet in the release |
| open | a remote story/<n>-* branch that is neither in the release nor listed, and not already in the base |
| in flight | the version and pull request in .tp-release-inflight |
What changes
tp release query: read-only. It fetches the release remote, then prints these sections in order:- the last release, plus the commits on the base since it;
- the stories in the release, each with its issue and line (the fragment, or the story's title);
- the listed stories still to merge, in
after:order; - the open branches not in the release;
- the in-flight release, if any, and its PR state from the forge;
- the next version, worked out the same way
tp releasewould.
- Each section header gives its count, for example
In the release (2): #94, #95. --offlineskips the fetch and the forge, and says so.- Exit 0 always. It is a report, not a gate.
Acceptance
| Repo state | tp release query shows |
|---|---|
| no story branches, nothing since the last tag | last release; nothing to release |
fragments off, a story merged to the base since the tag |
it under "In the release"; next version from release_bump or the CHANGELOG |
fragments: true, release holds #46; #47 listed, unmerged |
#46 in the release; #47 listed; next version from the fragments |
a story/ branch on the remote, unlisted, unmerged |
it under "Open, not in the release" |
a story/ branch already in the base |
not shown (it's done) |
.tp-release-inflight names v0.28.0, PR #12 open |
In flight: v0.28.0, PR #12 open |
| forge unreachable | the git sections as normal; the PR state given as unknown with the error |
--offline |
no fetch, no forge; (offline: as of the last fetch) |
Out of scope
- Acting on the report (merging, listing a story); that's
tp release. - Branches that aren't
story/branches, and other repositories (#62). - Machine-readable output, until something needs it.
Decisions
none
Done when
- tests express the acceptance table and pass
- spec updated (
docs/release-workflow.md, README command table) - ADR written if a fork was resolved (none)
- roadmap ticked and stamped; changelog entry
- issue closed with a link to the release