Release planning process

Document version	Date	Summary
v1	2026-08-01	Define how a new release is opened and planned

Status: Draft

Related documents: release process, milestones, version architecture policy, epics, PBIs, known limitations, bugs, roadmap, and agent rules

1. Purpose

This document defines how the next release is opened, scoped, and planned after a previous release has been closed.

The release process is the closing contract. It archives completed records, resets the active planning documents, and locks the release with evidence, a tag, and a frozen branch. This document is the opening contract. It defines the order in which planning documents are written, what each step must decide, and how a scope is judged before it becomes work.

The two documents meet at the rollover. Rollover ends with empty active planning documents and a set of carried limitations and bugs. Planning starts from exactly that state.

2. Authority and inputs

Planning does not create authority on its own. A release becomes real only when it appears in milestones, an accepted version architecture document, epics, and PBIs. The document precedence in agent rules section 1 applies to every planning decision.

Planning reads the following inputs before it proposes anything:

Input	What it contributes
Product specification	The product outcomes that are still unbuilt
Milestone exit criteria	The unticked criteria that the milestone still owes
General architecture	The boundaries a release may not cross
Previous docs/releases/<version>/evidence.md	What is actually verified rather than assumed
Known limitations	The constraints carried into this release
Bugs	Deferred defects that may need an owner
Roadmap	Candidate direction and the reasoning already recorded
Ideas	Unpromoted proposals that a candidate scope may draw from

The roadmap has no authority. It preserves reasoning so that planning does not restart from nothing. A candidate direction becomes scope only when this process accepts it.

3. Entry conditions

Do not begin detailed planning until the previous release is closed. The closing state requires the release archive, the evidence file, the annotated tag, the frozen release branch, and the reset active planning documents described in the release process.

Planning may begin earlier than that only as a candidate note under docs/roadmap/, which creates no epic, no PBI, and no implementation.

4. Planning order

Planning follows a fixed order. Each step depends on the accepted output of the step before it, so a step must not start while the previous step is still open.

flowchart TD
    S0[Step 0 Candidate selection]
    S1[Step 1 Milestone entry]
    S2[Step 2 Version architecture]
    S3[Step 3 Epic map and dependency diagram]
    S4[Step 4 PBIs]
    S5[Step 5 Limitation and bug intake]
    S6[Step 6 Roadmap reconciliation]

    S0 --> S1
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> S6

The order exists because each document answers a question the next one assumes. A milestone entry without a selected candidate invents scope. An epic map without an accepted architecture invents building blocks. A PBI without an epic invents its own acceptance.

4.1 Step 0, candidate selection

Choose the release outcome before writing it down anywhere authoritative.

Review the previous release evidence, the carried limitations, the deferred bugs, the unticked milestone exit criteria, and the roadmap candidates. Then state one primary outcome and the reason the project needs it now rather than later. Section 5 defines how that choice is judged.

The output of this step is a short accepted statement of the release outcome, its title, and its version number. It is not yet a document of its own.

4.2 Step 1, milestone entry

Add the release to milestones as its own section, following the shape used by the previous releases.

The entry must contain the release title, its milestone, its status, a placeholder link for the version architecture document, the release goal, expected capabilities, expected exclusions, and release exit criteria. Add the release to the known release table and update the milestone diagram.

Exclusions are as important as capabilities. An unstated exclusion becomes an argument during implementation, and section 8 defines how exit criteria are written.

At the end of this step the release is Planned and its architecture is not yet accepted.

4.3 Step 2, version architecture

Write docs/arch/arch-<version>.md under the version architecture policy.

The document follows the arc42 structure required by that policy and links to the general architecture instead of copying it. It must decide the building blocks, the source layout, the interfaces, the runtime flows, the deployment targets, the verification approach, and the support claims the release intends to make.

Record a decision with meaningful alternatives as an ADR under docs/adr/ rather than burying it in prose. An ADR is the durable record. The architecture document references it.

The architecture is accepted when the maintainer marks it accepted and the milestone entry links to it. Epics are not written before that point, because an epic map is a decomposition of the accepted architecture rather than a wish list.

4.4 Step 3, epic map and dependency diagram

Add the release epic map to epics, continuing the permanent identifier sequence recorded in that document.

Every epic states a verifiable outcome, its scope, and its completion criteria. An epic describes a product or engineering outcome rather than a source directory, a phase, or an activity. Section 6 defines how many epics a release should hold and section 7 defines their shape and ordering.

The epic dependency diagram is mandatory. A release epic map without a Mermaid dependency diagram is incomplete, because the diagram is the only place where the intended order of the release is visible at a glance. Follow the diagram with prose that justifies the edges that are not obvious.

4.5 Step 4, PBIs

Decompose each epic into PBIs in PBIs, continuing the permanent identifier sequence recorded in that document.

Each PBI follows the structure in that document, satisfies its shared Definition of Done, belongs to exactly one epic, and produces one reviewable outcome with testable acceptance criteria. A PBI set should cover its epic completely before later epic implementation PBIs are marked ready.

Order the backlog by dependency and risk rather than by comfort. A PBI whose acceptance criteria cannot be checked by a command, a test, or a recorded observation is not ready.

4.6 Step 5, limitation and bug intake

Decide which carried records this release owns.

For every entry in known limitations, decide whether the release closes it, narrows it, or carries it unchanged, then link the owning PBI in its tracking column. Apply the same decision to every open entry in bugs. A limitation that no PBI touches stays open and untouched by design rather than by omission.

A release that closes or narrows a limitation must say so in its milestone exit criteria, so the claim is checked at release time rather than remembered informally.

4.7 Step 6, roadmap reconciliation

Update the roadmap last, once the scope is authoritative elsewhere.

Remove or rewrite roadmap text that the accepted documents now own, because two descriptions of the same scope will disagree eventually. Keep the reasoning that is still candidate reasoning for later releases. Roadmap documents describe candidate direction without depending on which release is currently open.

5. How a release scope is chosen

A candidate is judged against the following questions. They are ordered by how often they change the answer.

Does it produce one primary outcome? A release has one sentence that explains why it exists. Work that does not serve that sentence either belongs to a different release or must be justified as unavoidable support work.

Does it produce the evidence the next decision needs? The project plans one release ahead with confidence and several releases ahead as direction. The best candidate is the one that converts the largest current unknown into recorded evidence, because that unknown is what makes later planning guesswork.

Does it alternate risk? Platform risk and product value are alternated deliberately rather than piled into one release. A release that adds hardware, storage, identity, and adapters at once cannot be verified independently, and a failure in any one of them blocks the rest.

Is it the smallest shape that still proves the point? Prefer the version of the candidate that removes the most scope while keeping the outcome truthful. Scope that is not needed for the outcome is a later release, not a bonus.

Does it leave something reusable? Prefer a foundation that the next release builds on over a disposable probe that answers a question and is then deleted. A probe is acceptable only when the answer is genuinely the whole value.

Can every claim be gated? Any capability the release claims must be checkable through the project gates, a test, or a recorded manual observation. A claim with no available check is either cut from the scope or recorded as a limitation before implementation starts.

Does it respect the Core boundary? No release may move product rules out of the Pet Core or move frontend, platform, storage, or hardware dependencies into it. A candidate that requires either is rejected or redesigned regardless of its product value.

Is it honest about support? A release claims only what its evidence supports. Cross-compile evidence is not runtime evidence, and one verified host is not a platform matrix.

When a candidate fails one of these questions, record the rejected shape and the reason. The roadmap keeps rejected shapes so that a later release does not rediscover the same argument.

6. Sizing a release

A release should decompose into roughly five to eight epics. Fewer usually means an epic is hiding several unrelated outcomes. More usually means the release is carrying scope that belongs to the next one.

An epic should decompose into roughly two to five PBIs. A single PBI epic is a sign that the outcome is really a PBI of another epic. An epic beyond five PBIs is usually two outcomes sharing a title.

These are planning heuristics rather than validation rules. Exceed them deliberately and record why in the epic map.

Every epic and every PBI must be independently verifiable. If a reviewer cannot tell whether an item is finished without reading the whole release, the item is scoped wrongly.

7. Epic shape and ordering

The first epic of a release owns the release architecture and scope. It ends when the version architecture document is accepted and the release scope is recorded, so that later epics implement a decided design rather than negotiating it.

The last epic of a release owns release verification and hardening. It ends when the required gates pass, the evidence is recorded, the limitations and bugs are reconciled, and the support claims match the evidence.

Between them, epics are ordered so that a boundary is established before work depends on it. Build and dependency infrastructure precedes the code that uses it. A platform foundation precedes the runtime that sits on it. Presentation cleanups follow the state they present.

The dependency diagram must be a directed acyclic graph. A cycle means two epics share one outcome and should be merged or split differently. Every edge is a real ordering constraint rather than a preference, and an edge that only reflects the order someone intends to work in does not belong in the diagram.

8. Writing release exit criteria

Exit criteria are the release contract. They are checked at closing time and archived with the release, so they are written to be checkable by someone who did not plan the release.

A criterion states an observable outcome rather than an activity. It names the evidence that satisfies it where the evidence is not obvious. It avoids words that cannot fail, such as improved, better, or cleaner.

Every capability claimed in the milestone entry needs a criterion that would catch its absence. Every limitation the release promises to close or narrow needs a criterion naming it. Every support claim needs a criterion bounded by the evidence that will exist, which is why criteria distinguish build evidence from runtime evidence.

A criterion that cannot be checked at closing time is a limitation in disguise. Record it in known limitations during planning instead of promising it.

9. Version numbers

Releases follow Semantic Versioning 2.0.0. During major version zero, a new capability increments the minor version and a compatible fix increments the patch version.

Choose the version number during step 0 and use it consistently from the milestone entry onwards, because the architecture file name, the archive directory, the tag, and the frozen branch all derive from it. Do not reserve version numbers for candidates in the roadmap, because a candidate that is reordered or dropped leaves a permanent gap in the reasoning.

A patch release fixes a defect on a frozen release branch. It does not open a planning cycle, does not add epics, and does not create a documentation rollover.

10. Major version transitions

A major version transition is planned rather than reached by accident. It happens when the current major version has satisfied its milestone exit criteria and the project can state the scope and the compatibility promise of the next major version clearly.

Planning a major transition adds the following work to the normal order:

Review the milestone exit criteria. Every criterion of the closing milestone is ticked or explicitly dropped with a reason. An unticked criterion is either delivered by one last release of the current major version or removed from the milestone deliberately.

Archive the milestone document. The milestone document is archived once per major version, immediately before the transition. It is not archived during a minor rollover. The rule and the archive location are defined in the release process section 3.3.

Open the next milestone. The new milestone document states the intended outcome, its constraints, its known releases, and its provisional exit criteria, in the same shape as the closing one.

State the compatibility promise. A major version boundary is the moment to define what the project promises to keep stable, which is a product decision rather than a release note.

Review the specification. The specification is a living document, and a major transition is the point where accumulated product evidence is folded back into it.

11. Planning checklist

Use this checklist when opening a release:

- [ ] Confirm the previous release is closed, archived, tagged, and rolled over.
- [ ] Review the previous release evidence, carried limitations, and open bugs.
- [ ] Review the unticked milestone exit criteria.
- [ ] Select one primary outcome and record why it comes now.
- [ ] Judge the candidate against the scope questions and record rejected shapes.
- [ ] Choose the version number.
- [ ] Add the release section to `01-milestones.md`.
- [ ] Add the release to the known release table and the milestone diagram.
- [ ] Record expected capabilities, expected exclusions, and exit criteria.
- [ ] Write `docs/arch/arch-<version>.md` under the arc42 policy.
- [ ] Record decisions with real alternatives as ADRs.
- [ ] Mark the version architecture accepted and link it from the milestone.
- [ ] Add the release epic map to `02-epics.md`, continuing the identifier sequence.
- [ ] Add the mandatory epic dependency diagram and justify its edges.
- [ ] Confirm the diagram is acyclic and starts and ends with the required epics.
- [ ] Add PBIs to `03-pbis.md`, continuing the identifier sequence.
- [ ] Confirm every PBI has one epic, one outcome, and testable acceptance criteria.
- [ ] Decide the release owner for every carried limitation and open bug.
- [ ] Link owning PBIs in the limitation and bug tracking columns.
- [ ] Update the roadmap and remove text that is now authoritative elsewhere.
- [ ] Set the release status to in progress when the first PBI starts.

For a major version transition, add:

- [ ] Tick or explicitly drop every closing milestone exit criterion.
- [ ] Archive the milestone document under the closing major version.
- [ ] Open the next milestone document.
- [ ] State the compatibility promise for the new major version.
- [ ] Review the product specification against accumulated evidence.

12. Special task rule

A release planning task is release maintenance in the same sense as a rollover. It does not update progress or last development unless a PBI explicitly requires that update.

Planning never implements. A planning task that starts changing source code has left its scope.