Rendered from docs/decisions/0090-each-release-states-in-its-notes-the-release-digest-that-a-consumer-pins.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

Each release states in its notes the release digest that a consumer pins

Context

Before this record, the reason lived only in two step comments. One was on the step "The digest the package in this tree publishes" of .github/workflows/release.yml (lines 350 to 365 on 2026-09-27). The other was on the step that attaches the archive in .github/workflows/release-taxonomy.yml (lines 139 to 145).

An adopter pins headwater/standard by its release.digest and passes the value to headwater taxonomy vendor --expect. gh release create --generate-notes writes a list of merged pull requests and a compare link, and nothing else. So an engine release that used only that flag stated no digest. v0.1.2 is such a release. README.md then sent a reader to the notes of a different tag for the value, which is #775.

Decision

Each release states the release.digest of headwater/standard in its release notes.

  • The engine release builds the text from the release record in the tree at the tag, .headwater/packages/headwater-standard/release.yml, in a step of its own. It passes the text with --notes-file together with --generate-notes. gh puts the text of the file first and adds the generated list after it.
  • The taxonomy release passes --notes with the digest that its own taxonomy publish run printed (HW-DR-0089).

The step of the engine release that writes the notes reaches no network, and it refuses a record that states no digest.

Consequences

An adopter reads the digest from the notes of the tag they downloaded, and never from the notes of a different tag. The digest is the value of the field in the release record. It is not what sha256sum prints for any one file.

The notes step of release.yml runs only on a pushed tag or a hand run. So tools/repo/readme-fixtures.sh finds that step by its name and runs it against the checkout. It compares what the step writes with the digest in the record of that checkout. A new name for the step is a red fixture until the fixture follows it (HW-PD-0012).