Skip to content

feat(release-tools): Change Note format and the gate that replaces verify:changelog #337

Description

@orioltf

Why

A guarded pull request currently writes four shared files, three of them on the same line, so two PRs against one Plugin always conflict. A Change Note is one new file per change, so two PRs write two different files and never collide.

Design and rationale: ADR-0035. Vocabulary: root CONTEXT.md.

What to build

The Change Note format

<issue#>-<slug>.md, frontmatter plus prose:

---
level: minor
section: Added
---

`/setup` installs the Archon artefacts from a named install set.
  • Plugin notes live in apps/claude-code/<plugin>/.changes/ and require level (patch|minor|major).
  • Repository notes live in the root .changes/ and must not carry level — nothing there is versioned. The parser rejects one.
  • section is Breaking, Added or Fixed in both.
  • The prose is the CHANGELOG bullet, used verbatim at release time. No transformation.

The gate

Replaces verify:changelog. It asserts that a Plugin whose files changed has at least one Change Note in that pull request.

Invert the guarded-path list to a deny-list. The current allow-list (packages/release-tools/scripts/lib/changelog-gate.mjs:5-12) omits lib/**, so a change confined there — where unic-archon-dlc keeps its implementation — is ungated today. An allow-list fails silently every time a Plugin grows a directory.

Deny-list starts at: test/**, **/*.test.mjs, CONTEXT.md, docs/**, .changes/**.

Acceptance criteria

  • A parser in packages/release-tools reads a Change Note and returns its level, section and prose. It rejects unknown frontmatter keys.
  • A Plugin note without level is an error naming the file. A repository note with level is an error naming the file.
  • A section outside Breaking|Added|Fixed is an error naming the file and listing the valid values.
  • The gate passes when a Plugin's changed files are all deny-listed, with no note required.
  • The gate fails when a Plugin file outside the deny-list changed and that Plugin has no Change Note in the diff.
  • A change touching only lib/** requires a note. A test asserts this specifically — it is the hole this ticket closes.
  • A change touching two Plugins requires a note in each. One note does not satisfy both.
  • Repository-scoped changes require a root Change Note under the same deny-list rule.
  • verify:changelog is removed, along with changelog-gate.mjs. The six Plugin package.json files point at the new command. CI wires it in place of the old step.
  • Every error message names the offending file path.
  • pnpm --filter @unic/release-tools test, pnpm typecheck and pnpm ci:check pass.

Out of scope

  • Consuming notes and bumping versions — that is the /release ticket.
  • Removing ## [Unreleased] from the Plugin CHANGELOGs — same, because bump-version is reworked there.

Activity

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

Metadata

Metadata

Assignees

Labels

featureNew capabilityp2Medium prioritypkg:release-toolsArea: packages/release-toolsready-for-agentFully specified, ready for an AFK agent

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions