Releasing a milestone
A milestone is a tracker version (v1.2.0) and the tickets attached to it.
Releasing it means promoting the integration branch (develop) to the
release branch (main), tagging it, and publishing the build.
Orion automates the steps around a release, and a person always makes the
decision. orion watch has no path to any release command, so an unattended
run can never cut a release.
1 · The milestone
| Command | Does |
|---|---|
orion plan KEY --release vX.Y.Z | Creates the version during planning and attaches the whole ticket tree to it |
orion release create vX.Y.Z | Creates a version by hand |
orion release add vX.Y.Z KEY... | Attaches tickets to it |
orion release list / status vX.Y.Z | What is open, and how far along a version is |
orion release close vX.Y.Z | Closes the version in the tracker |
Where a project uses versions, the watch only claims tickets that belong to an open one, so a ticket with no version waits until it is given one.
2 · Release notes
The agent that implements a ticket also writes .changelog.d/<KEY>.md: the
user-facing note for its change. One file per ticket means two tickets never
edit the same lines of CHANGELOG.md, so parallel work does not conflict.
orion changelog --version vX.Y.Z collates the fragments for a version into
a CHANGELOG.md section. With no fragments, it generates the section from
commit history instead. You rarely run it yourself: orion release ship
collates for you, inside the promotion pull request, where the notes are
reviewed with everything else.
3 · Verify
orion release verify vX.Y.Z
runs the promotion checks and reports; it changes nothing. Anything that would publish something wrong blocks; anything merely worth knowing warns.
| Check | Blocks or warns |
|---|---|
| Every ticket in the version is Done | Warns. Unfinished tickets roll forward to the next version. |
| Every shipped ticket has a release note | Blocks. A Done ticket with no fragment would ship unannounced. |
| Release notes and tickets agree both ways | Warns when a note names no ticket in the version, or a ticket is missing from an existing section. |
develop is green on the exact commit being promoted | Blocks. A green build for a different commit proves nothing about this one. |
| Nothing is about to land | Blocks while pull requests into develop are open. |
| Every commit in the range belongs to a ticket | Warns. A commit with no ticket key is something to look at, not necessarily a reason to stop. |
4 · Ship
orion release ship vX.Y.Z
runs the ceremony in a fixed order. Each step is a safe place to stop; only the last two cannot be undone, which is why they come last.
- Preflight refuses a tag that is not
vX.Y.Z, the wrong branch, or a dirty working tree, and runs the verify checks. - Orion opens a promotion pull request from
developintomain, with the collated changelog folded in, or reuses an open one from an interrupted run. - CI runs on that pull request.
- Orion asks for approval in the project's channel and waits for a person to approve. See Slack and approvals.
- Orion merges the promotion.
- Orion tags, builds and publishes.
Every step, including every refusal, is recorded in the log.
| Option | Does |
|---|---|
--dry-run | Runs the preflight and prints what would ship; promotes, tags and publishes nothing |
--beta | A prerelease tagged vX.Y.Z-beta.N, cut straight from develop: no promotion, and it is not published to the package tap or bucket, so a stable user's upgrade never picks up a beta |
The bare orion release only prints these verbs. The verb that publishes has
to be named, so a half-typed command can never reach a public tag.
The design is in
ADR 0036; why Orion owns
landing on develop in the first place is
ADR 0011.
Not documented yet
- What "publish the build" produces for a project Orion built, beyond the tag.