Skip to content

chore(repo): adopt engineering-conventions 0.7.0 and enforce every family - #164

Merged
justinmerrell merged 1 commit into
mainfrom
chore/conventions-0.7.0
Sep 30, 2026
Merged

justinmerrell merged 1 commit into
mainfrom
chore/conventions-0.7.0

Conversation

@justinmerrell

Copy link
Copy Markdown
Contributor

Adopts engineering-conventions 0.7.0 and enforces every family (ADR 0037). Closes #163.

Checked against 0.7.0, main reported nine findings. This PR fixes all of them, and conventions check --fail-on warning now reports none.

What changes

  • Pin: github:musher-dev/engineering-conventions 0.6.1 → 0.7.0, relocked. The REPO-04 waiver is dropped (ADOPT-06).
  • Interfaces (OUT-03, IFACE-*):
    • .repo/outputs.toml moves to schema_version = 2.
    • The contract outputs become [[interfaces]]: one <family>-schema per kind family, json-schema, gated, delivered by <family>-release.
    • The site joins as kind = "site", published by deploy.yml.
  • contracts:* tasks (IFACE-11..13): taskfiles/contracts.Taskfile.yml wraps the existing checks.
    • check runs check:schema, check:generated and check:examples.
    • breaking runs check:compat.
    • bundle runs release:stage.
    • Validate runs task contracts:check contracts:breaking ci:test. release.yml stages through contracts:bundle, falling back to release:stage for pre-0037 tags.
  • Release record:
    • Each kind family archive now carries the conventions' release.json, validated against release-record.schema.json.
    • Our existing record moves to specification.json, with the same content. Core carries only specification.json.
    • release.yml reads either name.
  • Release rules:
    • REL-06: release PRs are titled chore(release): …, and release is added to every copy of the scope list.
    • REL-13: the tag ruleset gains a creation rule, with the musher-release App (4991671) as its one bypass actor.
    • REL-18: SHA256SUMS is written and uploaded, and actions/attest runs with subject-checksums.
    • REL-19: drafts are published with a release App token.
  • Enforcement: check:conventions runs --fail-on warning, with no [adoption] table. CFG-01..08 retire in favour of CONF-01..09, and RUL-09 in favour of GHA-15. CFG-09 and RUL-01..08 stay.
  • Listing §9: corrects a sentence that still described v1 as unreleased. This is the releasable change, so merging cuts listing 1.0.1 and exercises the new release path end to end.

Deviations from #163

  • compatibility = "gated", not "versioned". versioned needs .vN. in each file name (IFACE-07), but here the major is the directory. A break needs a new v<N>, which is exactly what gated promises.
  • delivered_by takes one value, so each interface is delivered by its family bundle, which carries the record. The site is its own output.

Before merging: apply the tag ruleset

A creation rule without the App bypass would stop release-please from tagging. Apply the new ruleset first:

gh api -X PUT repos/musher-dev/specifications/rulesets/20585889 --input .github/rulesets/release-tags.json

What the listing release should show

  1. The release PR is titled chore(release): release listing 1.0.1 and passes check:title.
  2. The tag is created by the App through the bypass.
  3. The draft gets listing.schema.json, listing-v1.0.1.tar.gz and SHA256SUMS, with one attestation via subject-checksums.
  4. The archive holds listing-v1/release.json (the conventions record) and listing-v1/specification.json.
  5. The release is published by the App and reported immutable.

BEGIN_COMMIT_OVERRIDE
chore(repo): adopt engineering-conventions 0.7.0 and enforce every family
docs(listing): state that closing a known debt needs a new major now that v1 is released
END_COMMIT_OVERRIDE

🤖 Generated with Claude Code

…mily

Bump the conventions pin to 0.7.0 and fix every finding (ADR 0037):
declare each kind family's schema as an interface delivered by its bundle,
add the site output and the contracts:* tasks, ship the conventions release
record as release.json in each kind family archive (our record moves to
specification.json), attest releases through SHA256SUMS, publish drafts as
the release App, block release tag creation with the App as the one bypass
actor, and title release pull requests chore(release).

check:conventions now runs with --fail-on warning, and CFG-01..CFG-08 and
RUL-09 retire in favour of CONF and GHA-15.

Also correct listing §9, which still described v1 as unreleased.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Justin Merrell <merrelljustin@gmail.com>
@github-actions

Copy link
Copy Markdown
Contributor

You own some of the paths this pull request changes

@justinmerrell, this pull request touches paths you are a code owner for. Your authorship waives the code-owner review requirement — GitHub cannot request a review from a pull request's author — so nobody is automatically notified about these changes:

  • .github/rulesets/RULESETS.md — you are the sole owner; no review will be requested
  • .github/rulesets/release-tags.json — you are the sole owner; no review will be requested

Double-check they are intentional. If you want a second pair of eyes, request a review manually. (Automated notice from the repository-codeowners-notice workflow — ADR 0015.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Adopt engineering-conventions 0.7.0: replace contract outputs with interfaces

1 participant