Skip to content

Draft — not approved. A working draft by UASK. It may change without notice.

Release spec for one release or significant change

Status
Review
Version
0.1.5
Authority
UASK standard
Applies to
Core
Markdown source

Summary

A release spec is a short document that says what one release or significant change will do, how it will be checked and how it will be undone, before anyone builds it. It has the shape of a design doc: context and scope, goals and non-goals, design, alternatives, cross-cutting impact, then the checks, the rollout and rollback, the work packages and the open questions. It replaces an ad-hoc task list, it is where the appetite of the release is fixed, and it is approved at gate G2 before Build starts. It is not the requirements specification, which describes a product.

Rules

When and where

  • R1. A release or change of the class change or system change (process.project-lifecycle#R10) MUST have a release spec approved before Build starts. A fix MUST have at least the plan of the fix: the failing check, the backup and the rollback, in the issue or the pull request.
  • R2. The release spec MUST be a file in the project’s repository, with an id (RS-NNN, or the release version) that is never reused. Its front matter MUST give the id, the status, the tier, the appetite, the approver and the versions of the PRD and the Blueprint it builds on.
  • R3. The client’s own terms of reference MUST NOT replace a release spec. They stay an input, digested into the PRD, and the release spec cites the requirement ids that came from them.

Content

  • R4. Context and scope MUST say why this release comes now and what it builds on.
  • R5. Goals MUST list the requirement ids in scope and the ids explicitly out of scope. Non-goals MUST list what could be a goal but is not.
  • R6. Design MUST state which sections of the Blueprint change, by section number, the interfaces and contracts that change, and every data migration.
  • R7. Alternatives considered MUST list the options rejected and why. Each hard-to-reverse choice in the release MUST become an ADR (arch.adr).
  • R8. Cross-cutting impact MUST state security, privacy, performance, accessibility and observability, but only what the release changes.
  • R9. Acceptance and verification MUST state the acceptance criteria (req.acceptance-criteria), the checks to add first, red before green, and the evidence that will be shown.
  • R10. Rollout and rollback MUST give the release steps and the cutover order, how each step is undone and how long that takes. For a live system it MUST also name the backup that process.project-lifecycle#R11 requires.
  • R11. Work packages MUST each state a goal, the files they touch, a Done criterion and an estimate. The sum of the estimates MUST be compared with the appetite.
  • R12. Risks MUST name what could exceed the appetite and the circuit breaker: when the appetite is reached without the work done, the lead MUST stop and put the options and a default to the owner. It MUST NOT extend the work in silence.
  • R13. Each open question MUST carry a default that applies if nobody answers.

Approval and change

  • R14. The lead MUST approve the release spec at G2. The owner MUST approve it when it changes the scope or the appetite, or needs an owner-level decision (mgmt.roles-and-decision-rights#R9). On a client project, the client MUST approve it through the owner.
  • R15. A change of scope or appetite after approval MUST be made as a new revision of the release spec and approved as in R14. A builder MUST NOT change an approved release spec.
  • R16. The release spec MUST include the sections that its tier requires (the table under Guidance). A section that does not apply MUST say “none” and not disappear.
  • R17. When the release ships, the release spec MUST be closed with a link to the release record and a line that compares the actual effort with the appetite.

Guidance

The shape

The sections follow a design doc (Ubl): context and scope, goals and non-goals, design, alternatives considered and cross-cutting concerns. The Hub adds the parts a release needs: checks first, rollout and rollback, work packages with an appetite, risks and open questions. Use templates/release-spec.md.

The template is template: release-spec/1. tools/check_artifacts.py finds a spec in specs/ (also release-specs/) or by the name RS-NNN.md, and checks its front matter, its status and the sections its tier requires.

# Section Must say
0 Front matter id, status, tier, appetite, approver, versions of the PRD and Blueprint
1 Context and scope why this release now; what it builds on
2 Goals and non-goals ids in scope; ids explicitly out; things that could be goals but are not
3 Design Blueprint sections changed; interfaces and contracts changed; data migrations
4 Alternatives considered rejected options and why; hard-to-reverse choices become ADRs
5 Cross-cutting impact security, privacy, performance, accessibility, observability: only what changes
6 Acceptance and verification acceptance criteria; checks to add first; the evidence expected
7 Rollout and rollback steps; cutover order; how each step is undone and how long that takes
8 Work packages goal, files, Done criterion, estimate; total against the appetite
9 Risks and rabbit holes what could blow the appetite; the circuit breaker
10 Open questions each with a default

Sections by tier

The tier is chosen under mgmt.governance-tiers; this table says only which sections a release spec of that tier carries. R means required, O optional. An optional section that is left out says “none”.

# Section Lightweight Standard High-assurance
0 Front matter R R R
1 Context and scope R R R
2 Goals and non-goals R R R
3 Design R R R
4 Alternatives considered O R R
5 Cross-cutting impact O R R
6 Acceptance and verification R R R
7 Rollout and rollback R R R
8 Work packages R R R
9 Risks and rabbit holes O R R
10 Open questions R R R

A release of the class change at the lightweight tier can be a page: sections 0 to 3, 6 to 8 and 10. At the high-assurance tier the release spec is also reviewed by a second verifier.

Release spec or requirements specification?

The word “specification” alone means the requirements specification, which says what a product must do and how well. A release spec says what one release changes and how the change is made safe. The first belongs to the PRD and lasts as long as the product; the second is written for a release and closes when the release ships. See the glossary terms Release spec and Specification.

Appetite and the circuit breaker

The appetite is the time the owner is willing to give the release, in agent-days or working days. It is fixed, and the scope is what bends (Shape Up). The work packages are estimated against it. When the total is above the appetite, the spec cuts scope before it asks for more time. The circuit breaker is the rule of R12: if the appetite runs out with the work unfinished, the lead stops and asks, and does not carry on and hope.

Checks first

Each acceptance criterion that a machine can check gets its check before the code: the check is written, run and seen to fail (red), and the work is done when it passes (green). A criterion that only a person can judge names who judges it and how. The expected evidence is named in section 6, so that the verifier knows what to ask for.

Rollout and rollback

Write the rollback before the rollout. For each step, say how it is undone and how long that takes. A data migration that cannot be reversed says how the data is restored from the backup instead. When the release touches a live system, section 7 names the backup that was proved by restore (process.project-lifecycle#R11) and where it is kept. The release checklist template (templates/release-checklist.md) is filled in from section 7 when the release is prepared.

Work packages

A work package is the unit that one builder takes: one goal, a short list of files, a Done criterion that someone else can check, and an estimate. A package that cannot be estimated is too big or unclear; split it or turn the unclear part into an open question with a default. The work-packages item (process.work-packages) says what a brief holds and what lets a package merge; the Definition of Ready and of Done are process.definition-of-ready and process.definition-of-done (copy forms: templates/definition-of-ready.md, templates/definition-of-done.md).

Client projects

On a client project the release spec is the document the client approves. Where the project has a client-visible part of its documentation, the release spec goes there with its version, and the approval is recorded by the owner. The client’s terms of reference stay in the project’s folder as received.

Explanation

Why a separate document. A product-level PRD and a system-level Blueprint do not say what this release changes, how it will be checked or how it will be undone. In practice that gap was filled by an ad-hoc task list, and reviews of past projects found what slipped through it: missing rollbacks, missing interface inventories, scope growing in silence. A release spec is short and fits one session’s context, so a builder can read it whole.

Why the design-doc shape. A design doc, as Google’s engineers describe it, has more sections than a release needs. The Hub keeps three of them: goals and non-goals, which stop the scope from sliding; alternatives considered, which record why not; and cross-cutting concerns, which catch the security and privacy points that are easy to forget. It adds what a release needs.

Why appetite. Shape Up’s idea is to fix the time and vary the scope. For a small team with agents as builders that fits well: the cost of a release is mostly agent-days, which can be counted, and the owner’s attention is spent once, on the bet.

Why checks first. A check that was never seen to fail proves nothing. Writing it first makes the Done criterion concrete and gives the verifier something to run.

Examples

Good. Release spec RS-007 for a small shop: appetite three agent-days, standard tier, the lead approves. Goals: FR-12 and FR-13 (a delivery-date field on the order); out of scope: FR-14, which waits for a courier’s interface. Non-goal: redesign of the checkout. Design: Blueprint section 5 gets one component; no interface change; one data migration that adds a nullable column. Alternatives: a free-text note (rejected: not searchable). Checks first: two tests, red then green. Rollout: after the nightly backup, restored on the staging copy; rollback: drop the column, ten minutes. Three work packages, each with a Done criterion; the sum is 2.5 agent-days. Open question: “which date format?”, default “ISO”. The spec closes with the release record and “actual 2.8 days”.

Bad. “Add delivery date to checkout” as a one-line ticket. No goals or non-goals, so the builder adds a calendar widget and a courier integration. No checks, so the field passes review while it fails on phones. No rollback, so removing the column after a bad import takes a night. Three rules are missed: R5, R9 and R10.

Sources