Specifications on Brian Faust

Engineering Follow-ups

Sat, 25 Jul 2026 00:00:00 +0000

Abstract

The Engineering Follow-ups Specification defines a portable record for work that must happen before, after, or independently of another engineering event. A follow-up can block a merge, begin after deployment, become due at a fixed time, wait for a condition, or recur until an explicit stopping rule is met.

Pull-request checkboxes and incident action lists are useful presentation surfaces, but they are not durable execution records. They commonly lose the trigger, owner, deadline, verification procedure, evidence, or reason that made the action necessary. This specification keeps those semantics in one independent record that can be linked from a pull request, changeset, release, decision, postmortem, or another follow-up.

Incident Postmortems

Sat, 25 Jul 2026 00:00:00 +0000

Abstract

The Incident Postmortems Specification defines a portable record for explaining an incident after response. It separates what was observed from what was reported, inferred, hypothesized, and decided; preserves uncertainty instead of manufacturing precision; and connects learning to durable Engineering Follow-ups.

An incident can be resolved before its explanation is reviewed. A postmortem can be amended without rewriting the incident. This specification therefore keeps the operational incident lifecycle, postmortem publication lifecycle, causal analysis, disclosure, and corrective work distinct.

Release Manifest

Mon, 01 Sep 2025 00:00:00 +0000

Abstract

The Release Manifest Specification defines an immutable evidence record for one published release of one release stream. It answers a question that commits, changesets, and changelogs deliberately do not: what exactly shipped?

A manifest binds the release identity to:

the source repository, commit, and tag;
the published Intent Changelog record and its digest;
the release decisions represented by that record;
every declared artifact and its cryptographic digest; and
optional supply-chain evidence such as an SBOM or build attestation.

A manifest is not a deployment plan, package-manager command, mutable release dashboard, or substitute for a changelog. It records a completed publication boundary in a form people, CI, and downstream automation can verify.

Intent Changelog

Fri, 01 Aug 2025 00:00:00 +0000

Abstract

The Intent Changelog Specification treats an unreleased release as a real release whose publication date is not yet known, not as an inbox of uncategorized changes.

Each release record belongs to one release unit and contains complete, categorized entries. An entry records what changed, why it changed, who needs to know, its release impact, migration guidance, and its provenance. Projects may define their own change types without forcing unrelated changes into a fixed universal taxonomy.

Intent Changesets

Tue, 01 Jul 2025 00:00:00 +0000

Abstract

The Intent Changesets Specification defines a small, structured artifact for one independently understandable release decision. A changeset explains what consumers will experience, why the change exists, which release units it affects, and what release impact each unit should receive.

Intent Changesets sits between commit history and release history:

Intent Commits Specification messages record the intent of atomic Git changes and link to a changeset with a Changeset trailer;
Intent Pull Requests records may link reviewed integration context to one or more changesets;
an Intent Changesets record combines one or more commits or pull requests into one releasable decision; and
Intent Changelog Specification entries consume that decision into the canonical release ledger.

An Engineering Follow-ups record MAY use a changeset or its published release as its source. The changeset MUST NOT absorb the follow-up’s owner, trigger, due time, or completion state.

Intent Pull Requests

Sun, 01 Jun 2025 00:00:00 +0000

Abstract

The Intent Pull Requests Specification defines what a pull request must communicate before people or automation decide whether to integrate it. A pull request is a review artifact: it describes the complete proposed result, why that result is needed, how the implementation achieves it, why that approach was selected, what it affects, and what evidence supports its claims.

A pull request resembles a small changelog because both explain change. Their audiences and timing differ. A pull request helps reviewers decide whether a proposal should become history. A changelog helps consumers understand history that was released.

Intent Commits

Thu, 01 May 2025 00:00:00 +0000

Abstract

The Intent Commits Specification is a lightweight protocol for commit messages. It preserves the familiar type(scope): description header while separating four concerns that are often conflated:

the kind of work performed;
the area affected;
the release impact requested; and
the information consumers need to adopt or reverse the change.

Intent Commits uses Git-compatible trailers for machine-readable metadata. A commit type classifies the work; it does not determine a version increment by itself.

Project Profile

Tue, 01 Apr 2025 00:00:00 +0000

Abstract

The Project Profile Specification defines one versioned YAML document that connects Intent Commits, Intent Pull Requests, Intent Changesets, Intent Changelog, Release Manifest, Engineering Follow-ups, and Incident Postmortems records to a repository’s actual boundaries and policies.

The other specifications deliberately avoid prescribing one universal set of types, scopes, release units, audiences, channels, or versioning rules. Without a portable profile, however, two implementations cannot resolve those project-defined values in the same way. This specification makes that shared policy explicit.