Start a changelog and trim the release runbook - #46
Merged
Merged
Conversation
Release policy lived in eight places across three repositories, and this runbook carried per-release prose that went stale after 0.8.0. The service repository owns that policy, so RELEASING.md keeps only the mechanics: npm version, the v tag, the publish workflow, and the publisher settings. The tag rulesets block only deletion and non-fast-forward moves, so the runbook states the no-move rule as policy rather than as something GitHub enforces. Dist-tag repair lives in the public skills repository. The local guide is a hand-edited gist copy of the service's local-app.md, and the 0.8.0 release skipped republishing it. The service repository owns that page and its publication, so this runbook drops the republish step. The links stay on the gist until the service serves the page at a public URL. docs/release-history.md stopped at 0.4.0. It is frozen as history, and CHANGELOG.md takes over, written in the pull request that sets each version. Its headings carry no release status, and the documentation tests reject one, so nothing edits the file after publication. The publish workflow refuses a tag whose version has no entry. Finding that only at tag time would burn the tagged version, so CI also checks any version that has no tag yet. The package shipped RELEASING.md and the release history to every user, including inside the Skills plugin. Both now stay in the repository. Packaged pages link them on GitHub, and the link tests follow those absolute links into the checkout. The Skills copy of the package file list drops the same two paths when Skills next bundles this CLI.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Step 8 of the 2026-09-29 agent-documentation audit: one release entry point, with each repository keeping only its own mechanics.
RELEASING.mdis rewritten to cover mechanics only:vtag and the publish workflow;The gist republish step, smoke policy and per-release prose are gone. The service repository coordinates releases.
CHANGELOG.mdstarts here. The version-bump PR writes each entry.docs/release-history.mdis frozen as Historical.Changelog gates.
publish.ymlfails when the tag's version has no entry. The CI quality job fails earlier, in the version-bump PR, whenpackage.jsonnames an untagged version without an entry.Package contents. The npm package no longer ships
RELEASING.mdordocs/release-history.md. Packaged pages link them by absolute URL, and the documentation test resolves those URLs locally.AGENTS.md:AGENTS.md,CLAUDE.mdandRELEASING.mdnow trigger review;docs/review-focus.mdand record the reviewer, session id and verdict in the PR body, without findings;Merge after the skills companion, because
RELEASING.mdlinks itsdocs/dist-tag-repair.md. Skills'packedFileAllowlistdrops the two excluded files only when skills re-pins to a CLI revision that contains this change.Validation
npm run check: pass (theAGENTS.mdbudget is 1,818 of 2,048 bytes)npm audit: cleanReview
codex-review 0.7.3, max effort, read-only, with the service repository's
docs/review-focus.mdas the focus file.de07bbb5-209d-480b-a5c1-1dd29d81ecb0at ee5e2d1: Approve.07ca3eb7-2822-4991-b1e2-87219966ac8aat f2a2bb8, after theAGENTS.mdamendment: Approve.