Specifications on Brian Faust

Intent Pull Requests

Tue, 21 Jul 2026 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 Changelog

Mon, 20 Jul 2026 00:00:00 +0000

Abstract

The Intent Changelog Specification defines a structured release ledger for software projects. It treats an unreleased release as a real release whose publication date is not yet known, rather than 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

Mon, 20 Jul 2026 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.

A changeset is not a release, changelog, pull request template, version-bump command, or mandatory file for every commit. Projects define which changes are noteworthy enough to require one.

Intent Commits

Mon, 20 Jul 2026 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

Mon, 20 Jul 2026 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, and Release Manifest 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.

Release Manifest

Mon, 20 Jul 2026 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.