Skip to main content

How to manage releases

When you'd do this: when you want to bundle a set of stories into a deliverable unit of work, get it ready for build, hand it to a builder, and accept the result.

A release is the deliverable unit in REQQA: a named bundle of stories with a status, a lifecycle, an optional build plan, quality checks, and point-in-time snapshots. In the underlying data model the object is a scope — code paths, URLs (scopesList, scopeView) and table names all use scope* — but everywhere you see it in the interface it is called a Release. The "scope" of a release is one of its properties: what's in it, what's deliberately left out, and the constraints it operates under.

This page walks you through the whole release cycle as an analyst working in the UI. Builders (such as an AI build agent) do not drive releases through these screens — they act through the REQQA API with a restricted set of transitions. See Releases and scopes for the conceptual model and Scope vs Release for the naming.

Browse your releases​

Open Releases from the navigation. The list (scopesList) shows every release for your currently selected application, most-recently-updated first, with a story count against each. If no application is selected you'll be sent to pick one first.

Three view tabs filter the list:

  • Active (the default) — releases in draft or handover_ready.
  • Closed — releases that are accepted or abandoned.
  • All — everything.

Each tab carries a count, and you can narrow further with an explicit status filter; Clear Status removes that filter. Each row offers View (the detail page) and, while the release is still a draft, Edit.

Create a release​

  1. On the releases list, click New Release.
  2. Fill in the form (scopeAdd):
    • Name — required, and must be unique within the application.
    • Description — what this release delivers.
    • Out of Scope — what it deliberately does not cover.
    • Constraints — limits the delivery must respect.
  3. Click save.

The release is created in Draft status, an initial entry is written to its status history, and you land on its detail page.

tip

Name releases the way your team actually talks about them — "v2.1", "Onboarding MVP", "Billing". The name is what everyone searches and refers to.

Edit a release​

Click Edit on a draft row, or Edit from the detail page, to reopen the same form (scopeEdit) populated with current values. The unique-name rule still applies.

caution

Only draft releases can be edited. Once a release moves to Handover Ready its name, description, scope notes and constraints are locked, and the same applies to its story contents — this is what makes the as-scoped snapshot meaningful. If you need to change a handed-over release, transition it back to Draft first.

The release detail page​

The detail page (scopeView) shows the release name, its current status, and a row of tabs. Across the top sit the page actions: a Transition Status dropdown (only shown when there are valid moves available), All Releases, Index Glossary Terms (populates the glossary appendix used by the PDF report), and a report download button.

Overview​

A summary: status, story and requirement counts, and key dates such as when the current plan was marked done.

Stories​

The stories included in this release, grouped by their parent requirement. While the release is in Draft, an Add Stories control lets you pick stories to include; each story is pinned to its current revision at the moment you add it, and you can remove stories too. Once the release leaves draft, the contents are fixed. Each story shows its DeFOSPAM analysis progress and any open HIGH / MEDIUM issue counts. Generate stories first via generating stories if a requirement has none.

Quality Gate​

An advisory readiness check (results do not block transitions). It runs four checks across the in-scope artefacts:

  • Requirement analysis coverage — each in-scope requirement reaches at least the R-D, R-F, R-A, R-M DeFOSPAM steps (container requirements that carry no features are not expected to have R-F).
  • Story analysis coverage — each story reaches at least D-D, D-S, D-A.
  • No open HIGH-severity issues on in-scope requirements or stories.
  • No stale stories — none where the parent requirement was updated more recently than the story (a sign the story needs regenerating).

See analyser codes for what the step codes mean.

Static Analysis​

The static-analysis policy profile resolved for this release — the catalogue of checks, their dispositions and severity floors. Configure it via configuring static analysis.

Feedback​

Feedback items raised against this release. These are normally created by a builder during a build (through the API and the handover skill), but the tab also offers a manual entry form so you can record observations yourself during testing. Each item has a severity, a target artefact, and an optional suggested edit.

Plan​

The build plan(s) for this release — see below.

History and Snapshots​

History is the full status-transition audit trail (who changed what, when, with comments). Snapshots holds the immutable JSON captures: As-Scoped, taken automatically the first time the release reaches Handover Ready, and As-Built, taken when the builder marks the plan as Done.

Drive the release lifecycle​

A release has four statuses, and you move between them with the Transition Status dropdown, which only ever offers the moves that are valid from where you are:

StatusMeaningValid moves
DraftBeing assembled; editable→ Handover Ready, → Abandoned
Handover ReadyLocked and offered for build→ Draft (revise), → Release Accepted, → Abandoned
Release AcceptedDelivered work confirmed after testing(terminal)
AbandonedNot being pursued→ Draft (un-abandon)

When you choose a transition, a confirmation modal opens where you can add a comment. Moving to Handover Ready runs the quality gate first so you can see any advisory failures before you commit, then captures the As-Scoped snapshot. The comment and the change are written to the release history.

note

Release Accepted (the analyst confirming the delivered work is good) is distinct from a plan being Accepted (Customer). The release status is your view of the release; plan status tracks the build cycle separately.

Build plans​

A release is handed to a builder as a plan — a structured Markdown document. From the Plan tab (or the full-page scopePlanView) you can submit plan content, which creates a new draft version (versions auto-increment; submitting a new draft supersedes the previous one). Plans can only be submitted when the release is Handover Ready and no other plan is already in flight.

As the analyst you then approve a draft plan. Approval is blocked if the plan still contains non-empty Blockers, Queries, or Unmitigated Risks sections — the builder must resubmit a v2 with those resolved (or reclassified as settled annotations such as Assumptions or Caveats). A plan has its own seven-state lifecycle — Draft, Approved, In Progress, Paused, Done (Builder), Accepted (Customer), Superseded — and scopePlanView lets you browse every version, see each one's status history, and apply the plan transitions that are yours to make.

Where builders fit in​

The build half of this lifecycle is designed to be driven by a builder through the REQQA API, not these screens. Analyst-owned moves — taking a release to Handover Ready, approving a plan, accepting the final delivery — stay in the UI you've just used. Builder-owned moves — starting the build, pausing and resuming, and signalling the build is done — are made by the build agent against the plan. This keeps the security boundary clean: the UI is the analyst's full lifecycle; the API exposes only the builder's restricted transitions. See The Dark Factory for how the two halves meet.

Result​

A release that moves cleanly from an editable draft, through a locked Handover Ready state with an approved build plan and an As-Scoped snapshot, to an accepted delivery — every step recorded in its history, every advisory check visible, and a downloadable report you can hand to a stakeholder.