Releases

A release is a curated, immutable snapshot of a chosen set of documents — think of it as a generalised baseline. Where a baseline freezes the whole workarea at one commit, a release freezes only the documents you pick, and each document at whatever revision you choose. That lets you assemble, say, “System 1.0 = SRS at its 1.0 revision + Architecture at its draft revision + ICD as it stands today” without waiting for every document to line up on the same commit.

A release has two phases:

  • Open — a working manifest of {document → revision}, where the revision may be a specific one you pinned or simply “latest on main”. You add and remove documents, change what each is pinned to, and resolve any conflicts. Everything is still editable.
  • Locked — the manifest has been assembled into a single frozen commit and can never change again. The locked release is a permanent, self-contained snapshot with its own git ref.

Because a release is built on the workarea’s git repository, locking does not copy your data — it assembles the pinned documents and their items into one immutable commit, exactly as they were at the revisions you chose.

The Releases page

Navigate to Releases in the sidebar. Releases are split across two tabs:

  • Open — releases you are still curating.
  • Locked — frozen releases, read-only.

Each release shows its name, its ID (REL-<workarea>-<n>), status, and who created it. Creating a release requires releases:create.

Creating a release

  1. Navigate to Releases in the sidebar.
  2. Click New Release.
  3. Enter a name and an optional description.
  4. The release is created Open with no documents yet.

The name is free text — use it for your human-facing version (1.0, 2.0-rc1, audit-gate-3). The stable REL-… ID is assigned automatically and never changes.

Curating members

Open a release to reach its detail page. The Documents section is where you choose what the release contains:

  1. Click Add documents to open the folder tree — the same document hierarchy you see in the workspace, with each document shown by its type icon and title. Tick the documents to include and confirm.
  2. Newly added documents start on Latest (tracks main) — you do not have to decide versions to decide scope. Such a document follows mainline as authoring continues, and is pinned to whatever is current at the moment you lock the release.
  3. To fix a document at a particular version instead, use the Revision picker. Revisions are labelled by their baseline name where one exists, otherwise by a short commit id, so you can recognise “the 1.0 baseline of the SRS” at a glance. Switch back to Latest (tracks main) at any time while the release is open.
  4. Remove a document with the trash icon.
  5. Click Save changes to persist the member set.

Note: Amending an item for the release (see below) pins that document, because an amendment is recorded against a specific version. The Documents panel tells you how many members still track main and will be pinned at lock.

Editing members is a full replace and requires releases:manage. The set you save is the set the release holds.

Resolving disagreements

Two member documents can each reference the same item but pin it at different versions — for example, the SRS pins requirement R-42 at one revision while the Test Spec pins an older one. A locked release must hold exactly one version of every item, so these clashes have to be settled first. The release calls them disagreements.

The Disagreements panel on an open release lists every shared item whose members disagree. For each one, pick the winning version with the radio buttons — each option shows which document contributes it, its document revision, and the item’s underlying blob id. A badge tracks how many disagreements are still unresolved. Items that only one document references, or that every document already agrees on, never appear here — there is nothing to decide.

Note: Disagreements are recomputed live from the current pins. Changing a member’s revision can introduce or clear a disagreement, so the panel always reflects the release as it stands right now.

Locking a release

When every disagreement is resolved (or there were none), the Lock release button becomes available — it requires releases:lock. Locking:

  • Assembles a single frozen commit containing only the pinned documents and one agreed version of each item they reference.
  • Records a snapshot of the workarea’s resolved configuration alongside it, so the release renders exactly as it did on the day it was locked even if type or enumeration configuration changes later.
  • Points a dedicated git ref (refs/rop/releases/<id>) at that commit, which keeps every pinned version permanently safe from garbage collection.

Locking asks for confirmation because it cannot be undone. After locking, the release is immutable: you cannot edit its metadata, change its members, or delete it. A “fix” to a locked release is a new release, never a re-lock of the old one — this keeps the audit trail honest.

Permissions: Viewing releases requires releases:view, creating them releases:create, curating members and metadata releases:manage, and locking releases:lock. Administrators hold all four automatically.

Opening a document in a release

From a release’s Documents list, click a document’s title (or Open in release view) to open the real document at the exact revision this release pins it to. This is the best way to review — or author — a release: you see the document as it will ship, not a table of revisions.

  • For a locked release the document is frozen at the release commit and read-only.
  • For an open release the document opens at its member pin, and — with releases:manage — it is editable, for this release only. You use the ordinary editor: type in the body, add and delete items, reorder sections, change heading levels, edit document properties. A Release edit chip next to Save says where the save lands. Saving writes one change to the release; the live document is untouched.
  • Without releases:manage the document opens read-only.

Status is the exception. A release edit records a frozen version of each item — it doesn’t run your workflow, so the status control stays read-only in a release. Move an item’s status on the live document, then bring the new version into the release with Update to revision.

Two other things a release edit cannot do, because they would change items outside this document: incoming links (edited from the Links tab of an item) are not saved — you’ll see a note if you queued any — and there is no draft/conflict flow, since the release pin only ever moves when you save.

An indigo banner across the top names the release you are viewing.

Inside a release document view, link targets resolve to the version the release pins — not to the live item. Each link badge (and the linked-items focus view) shows one of three things:

  • A member target — the item belongs to another document in this release. The badge shows the item at its pinned version, and clicking it opens that document in the same release view.
  • An outside target — the item isn’t part of the release. The badge shows the item’s title as of this document’s pin, marked as outside release, and clicking it opens the live item.
  • A missing target — the item can’t be resolved at this pin at all; the badge shows just its id.

Which releases is this work item in?

The other direction: open any work item — in the document side panel, in the items table, or on its own page — and the Releases tab (a card on the item page) lists every release that ships it.

Each row names the release, whether it is open or locked, the member document(s) that carry the item there, and whether that release holds the current version or a different version than main. Tick two or more rows — the current version is one of the choices — to compare them field by field; only fields that actually differ are listed.

This is a read-only view. To change what a release holds, open it and use the actions below (or edit the member document directly).

Updating specific items for a release

Editing the document directly (above) covers most of this. The right-click menu adds the things the editor has no gesture for, and stays useful when you want one precise change without opening the whole document. In an open release with releases:manage, open a member document and right-click a work item:

  • Edit for this release — change the item’s title, description, fields, or links as they should appear in this release. The live item is untouched.
  • Update to revision — adopt an older or newer version of just that one item, from its own history.
  • Insert item below — create a brand-new item that exists only in this release, placed after the one you clicked. Pick its type, give it a title, and optionally a description.
  • Remove from this release — drop the item from this document in the release. The live item is unaffected; it simply isn’t part of the release.

Every change is applied as a small, self-contained edit layered on top of the document’s pinned revision — the original is never modified. After a change, the view refreshes to show it, and edited items are marked with a small Amended badge; items you created show Added in this release.

If you’d rather work from a table, the open release’s Documents list lets you expand any member to the same per-item actions.

Undoing release edits

An amended member shows an Amended badge (with its original → current revision) and a Revert to original action that discards all release edits for that document and pins it back to where it started. Reverting undoes item edits, creations, and removals together.

Cutting the next version

When you’ve shipped a release and need to start the next one, open the locked release and click New version. This creates a fresh open release seeded with the same documents (at the same revisions), so you can re-pin, amend, and lock it as the next version. The new release records where it came from and shows Based on at the top; the source release is never changed. The suggested name bumps a trailing number — it’s only a suggestion, edit it freely.

Viewing the whole workarea as-of a release

A locked release is a snapshot of everything at that point, not just its documents. On a locked release, click Enter release to view the entire workarea as it stood when the release was locked — items, documents, traceability, and dashboards all show the frozen data. A banner names the release; Exit release returns you to live data.

Open releases can’t do this: they have no single frozen point (each document has its own pin), so entering an open release scopes only its member documents to their pinned revisions, while dashboards continue to show live data. The banner says as much.

What releases are not (yet)

Releases now cover assembling, freezing, versioning, and per-item authoring within a workarea. They do not yet cover:

  • Forward-porting fixes — automatically moving a release-only change onto main or into another release (the Based on link records provenance for you to do it by hand).
  • Cross-workarea and nested releases — a “release of releases” that bundles releases from several workareas.
  • Filtered dashboards while frozen — in a locked-release view, dashboard widgets that use a query filter currently show the whole snapshot rather than the filtered subset.