Specs and their revisions

Exact revisions

A spec says what's intended: what a product or one of its items should do, how it's designed, or how it will be checked. Intent changes, so "the spec" alone is never precise enough. In the BLOM method, anything that relies on a spec, such as a Job's brief or a review, names one exact revision, and that revision's text never changes.

So BLOM treats specs the way you treat code. You write and change them in your repository. BLOM reads them, and records exactly which text each revision held. See Specs and Revision identity in the method.

The eight document types

BLOM reads eight types of document. Each has one purpose.

The method also counts reviews as documents. BLOM records reviews on a Job instead of reading them from files. The facts BLOM keeps apart covers them.

How BLOM reads your repository

Once you connect a repository, BLOM reads the Markdown files on its Document branch, leaving out any Excluded paths. It reads with read access only and makes no change in GitHub. Connect a repository sets this up.

A file is a document when the lines at its top, before its first section heading, include an ID line naming one of the eight types. For Harbor's Invitations capability, a P-Spec might start like this:

# Invitations

    ID: P-Spec 1-1
    Home: 1 Member onboarding > 1-1 Invitations (Capability)
    Parent: none
    Owner: Ada Lovelace
    Revision: 1
    Governed by: S-Std specification r1

ID

The type and a name unique in your organization. BLOM knows the document by it.

Home

The item the document belongs to, as its path from the product, by number and name. BLOM places the document at the item whose number ends the path, in the product the repository is connected to.

Parent

For a P-Spec, the P-Spec of an item above it, or none.

Owner, Revision, Governed by

Who answers for the document, the revision it says it is, and the standards it was written against. BLOM numbers revisions itself, and notes any difference from the Revision line.

An S-Std also has a Category line, and an ADR has Status and Kind lines.

Each revision is pinned to a commit

When a commit on the document branch changes a document's content, BLOM records a revision pinned to that commit. A commit that leaves the content alone makes no new revision.

BLOM compares content, not every byte. It leaves out the record parts, such as the ID, Home, Parent, and Revision lines, and the Approvals, Revision history, and Corrections sections. Updating only those keeps the revision you have.

Each revision BLOM records has a number and a pin, written like r1 @ 4e1a9c2. A citation names both, so it always means the same text, whatever happens to the file later.

Approving a revision

A document revision is approved for a purpose, such as Build, by one person's sign-off. The person is the one the document gate names, in the PDLC that governs the document's home. The approval binds that exact revision, its purpose, and its scope: the whole document, or the sections the approver names.

One revision can hold approvals for different purposes, and a newer revision holds none until someone approves it. An approval says the revision may be used for its purpose. It isn't proof that anything was built: see The facts BLOM keeps apart.

A Job names the revisions it follows

A Job's brief says what the work is for: its desired outcome, its target items, and the documents that govern it. Each citation names an exact revision and pin. It can also say which part applies, such as a requirement or an acceptance criterion, and what the Job does with the document, such as implement it or revise it.

A citation stays put. When a document gets a newer revision, the Job still cites the one it named, until someone revises its brief to cite the newer one. The Job's page says when a newer revision exists. That's how a Job builds against the text it was given, even while someone else revises the spec.

On a Job's page, Revise the brief changes its outcome, its target items, and the revisions it cites, each with the part that applies and what the Job does with it. Citations can also be set when a Job is captured, or its brief revised, through the public API, the CLI, or an agent's blom_capture_task. See How tasks relate to specs in the method.

The citations show in the Job's Handoffs section:

• A context export supplies each cited document's text at its exact revision. For a file in your repository, that's the file as it was at the pinned commit.
• A closure's record shows what was In effect when returned: the brief revision, and each governing document's revision and pin.

Handoffs covers both.

Documents BLOM holds itself

Two kinds of document live in BLOM instead of your repository: standards written in BLOM, and each PDLC's own standard, the Markdown file with a section for each of its phases.

BLOM pins each saved revision of these by a fingerprint of its content, a SHA-256 hash, so it's as exact as a commit. A standard's page lists each revision with the start of its pin. A PDLC version is approved together with the exact revision of its standard, which is pinned with it. See Standards and Your PDLC and its gates.

Templates and the starter set

Each document type has a template, which the standard governing that type defines. When you or an agent start a document, BLOM supplies the template from the standard revision in force at the document's home, and records which revision it came from, so the new document says what governs it from its first line. You create the file in your repository, and BLOM reads it like any other.

BLOM ships a starter set your organization can adopt: a template for each of the eight types, and templates for the recommended standard categories. Once adopted, the copies are your own, and later releases of BLOM never change them.

Seeing what BLOM read

Each document has a page of its own: where it sits, and each revision with its pin, its approvals, and the work that cites it. A P-Spec's page also lists its child P-Specs and the items under its home, including items that have no spec yet. An item's page lists the documents homed at it.

BLOM also shows documents where work uses them: in context exports and closures. An S-Std read from your repository also shows in the standards register, under Category unknown.

To list every document BLOM read from a repository, each with its revision and pin, call documents.listGit through the public API, or with blom op in the CLI. documents.readRevision returns one revision's text.

Related