Skip to content

docs(release): codify /admin/* semver discipline in release contract (Story 44.4)#67

Merged
ALLiDoizCode merged 3 commits intomainfrom
docs/release-contract-api-stability
May 8, 2026
Merged

docs(release): codify /admin/* semver discipline in release contract (Story 44.4)#67
ALLiDoizCode merged 3 commits intomainfrom
docs/release-contract-api-stability

Conversation

@ALLiDoizCode
Copy link
Copy Markdown
Collaborator

Summary

Story 44.4 of the Townhouse HS-Mode v1 epic. Documentation-only PR — no code, CI workflow, or TypeScript changes.

Doc edits in CONNECTOR_RELEASE_CONTRACT.md

  • New ## API stability section (inserted between ## Stability guarantees and ## Supply-chain signing): semver bump rules for /admin/* field/endpoint additions and removals, ILP wire-format changes, and image architecture changes.
  • ### Townhouse pin discipline subsection: describes how townhouse pins by digest in image-manifest.json and gates bumps on the SDK contract canary.
  • New ## Staying current section (inserted between ## Recommended pinning strategy and ## Historical tag corruption): GitHub Watch UI (preferred) + gh api CLI (fallback) mechanisms for release notifications; automation explicitly deferred as Open Thread Epic 7 #2.
  • Multi-arch sentence in ## Artifacts: adds explicit rule that adding architectures is build-only (no semver bump) and removing one is a MAJOR bump.
  • Town mirror drift-detection note in ## Verification: documents how to verify body-equivalence against the toon-protocol/town mirror file.
  • pull/<num> placeholder fix on two lines (Story 44.3 follow-up): both pull/<num> references for PR feat(release): cosign-sign connector + ATOR sidecar images via keyless OIDC #66 now correctly link to pull/66.

CHANGELOG.md edit

Added ### Documentation entry in [Unreleased]: Codify /admin/* semver discipline in CONNECTOR_RELEASE_CONTRACT.md (Story 44.4 / PR #). The docs(release) commit type maps to no semantic-release version bump — this PR alone does not cut a release.

Asymmetric CHANGELOG treatment (town side)

toon-protocol/town has no CHANGELOG.md at root, packages/townhouse/, or packages/sdk/ — town uses sprint-status.yaml + commit messages as its audit log. The town-side "changelog equivalent" for this story is:

  1. A "See also" cross-link added to packages/sdk/CONNECTOR_MIGRATION.md pointing to the new mirror.
  2. A row added to CLAUDE.md ## Where to Find Things.
  3. Sprint-status comment + town PR commit message.

This asymmetry is intentional. Adding a singleton CHANGELOG.md in town for one entry would be ceremonial noise with no semantic-release pipeline to consume it.

Town-side mirror content

The body of CONNECTOR_RELEASE_CONTRACT.md will be mirrored byte-for-body-identical at packages/sdk/CONNECTOR_RELEASE_CONTRACT.md in toon-protocol/town in a companion PR. The town file prepends a 3-line comment header (drift-detection aid); the body below that header is byte-identical to this file.

Body-equivalence is verified with:

diff CONNECTOR_RELEASE_CONTRACT.md \
     <(tail -n +4 /path/to/town/packages/sdk/CONNECTOR_RELEASE_CONTRACT.md)

Expected output: empty.

Test plan

  • grep -n "API stability\|Staying current" CONNECTOR_RELEASE_CONTRACT.md → section headings present
  • grep -nE "pull/<num>" CONNECTOR_RELEASE_CONTRACT.md → empty (placeholder fixup confirmed)
  • grep -n "Story 44.4" CHANGELOG.md → matches [Unreleased] entry
  • Semantic-release dry-run: docs(release) prefix → no version bump
  • Body-equivalence diff with town PR (after town PR opens): diff connector/CONNECTOR_RELEASE_CONTRACT.md <(tail -n +4 town/packages/sdk/CONNECTOR_RELEASE_CONTRACT.md) → empty

🤖 Generated with Claude Code

Developer added 3 commits May 8, 2026 12:08
- Add ## API stability section (semver bump rules for /admin/* and ILP wire-format)
- Add ## Staying current section (GitHub Watch + gh CLI subscription; automation deferred)
- Add multi-arch architecture change rule in ## Artifacts prose
- Add town mirror drift-detection note in ## Verification
- Fix pull/<num> placeholder on two lines → pull/66 (Story 44.3 follow-up, AC #7)

Story 44.4 / PR #<num>
@ALLiDoizCode ALLiDoizCode merged commit 005e03f into main May 8, 2026
32 of 34 checks passed
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 8, 2026

🎉 This PR is included in version 3.6.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

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

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant