From 7f1df7c1a888cb1117e6c3292a2914d5eeeb9bc2 Mon Sep 17 00:00:00 2001 From: Erik Marks <25517051+rekmarks@users.noreply.github.com> Date: Wed, 8 Apr 2026 10:54:08 -0700 Subject: [PATCH 1/3] docs: Move updating changelogs documentation to dedicated doc --- .gitignore | 1 + README.md | 29 +----------------------- docs/contributing/updating-changelogs.md | 29 ++++++++++++++++++++++++ 3 files changed, 31 insertions(+), 28 deletions(-) create mode 100644 docs/contributing/updating-changelogs.md diff --git a/.gitignore b/.gitignore index 244e09b48d..8c551a1174 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,7 @@ dist/ coverage/ docs/* !docs/*.md +!docs/contributing # Logs logs diff --git a/README.md b/README.md index 1e52e4c970..0288af039b 100644 --- a/README.md +++ b/README.md @@ -64,34 +64,7 @@ See [`packages/create-package/README.md`](packages/create-package/README.md). ### Updating changelogs -Each package in this repo has a file named `CHANGELOG.md` which is used to -record consumer-facing changes that have been published over time. All -changelogs follow the ["Keep a Changelog"](https://keepachangelog.com/) -specification (enforced by `@metamask/auto-changelog`). - -If a PR introduces a consumer-facing change to one or more packages, their changelogs must -be updated. This is enforced by CI. When updating changelogs, keep the following in mind: - -- A changelog is not a git history; it is a summary of consumer-facing changes introduced by - a particular release. - - Consider each PR from the perspective of a consumer of an individual package. Changelog - entries may differ between packages. - - For example, if you're introducing feature X to package A, and it contains an incidental - change Y to package B, the package changelogs should reflect this. -- Place new entries under the "Unreleased" section. -- Place changes into categories. Consult the ["Keep a Changelog"](https://keepachangelog.com/en/1.1.0/#how) specification for the list. -- Highlight breaking changes by prefixing them with `**BREAKING:**`. -- Omit non-consumer facing changes from the changelog. -- Do not simply reuse the commit message, but describe exact changes to the API or usable - surface area of the project. -- Use a list nested under a changelog entry to enumerate more details about a change if need be. -- Include links (e.g. `#123) to the pull request(s) that introduced each change. -- Combine like changes from multiple pull requests into a single changelog entry if necessary. -- Split disparate changes from the same pull request into multiple entries if necessary. -- Omit reverted changes from the changelog. - -If your PR does not contain any consumer-facing changes, add the label `no-changelog`, and the -changelog validation CI job will be skipped. +See [`docs/contributing/updating-changelogs.md`](docs/contributing/updating-changelogs.md). ### Releasing diff --git a/docs/contributing/updating-changelogs.md b/docs/contributing/updating-changelogs.md new file mode 100644 index 0000000000..af85321e5d --- /dev/null +++ b/docs/contributing/updating-changelogs.md @@ -0,0 +1,29 @@ +# Updating changelogs + +Each package in this repo has a file named `CHANGELOG.md` which is used to +record consumer-facing changes that have been published over time. All +changelogs follow the ["Keep a Changelog"](https://keepachangelog.com/) +specification (enforced by `@metamask/auto-changelog`). + +If a PR introduces a consumer-facing change to one or more packages, their changelogs must +be updated. This is enforced by CI. When updating changelogs, keep the following in mind: + +- A changelog is not a git history; it is a summary of consumer-facing changes introduced by + a particular release. + - Consider each PR from the perspective of a consumer of an individual package. Changelog + entries may differ between packages. + - For example, if you're introducing feature X to package A, and it contains an incidental + change Y to package B, the package changelogs should reflect this. + - Describe entries in natural language; do not simply reuse the commit message. +- Unless you're cutting a new release, place new entries under the "Unreleased" section. +- Place changes into categories. Consult the ["Keep a Changelog"](https://keepachangelog.com/en/1.1.0/#how) specification for the list. +- Highlight breaking changes by prefixing them with `**BREAKING:**`. +- Omit non-consumer facing changes from the changelog. +- Use a list nested under a changelog entry to enumerate more details about a change if need be. +- Include links (e.g. `#123) to the pull request(s) that introduced each change. +- Combine like changes from multiple pull requests into a single changelog entry if necessary. +- Split disparate changes from the same pull request into multiple entries if necessary. +- Only included reverted changes if they were previously released. + +If your PR does not contain any consumer-facing changes, add the label `no-changelog`, and the +changelog validation CI job will be skipped. From 09d67a6d731b848303c743cd0302877855988e84 Mon Sep 17 00:00:00 2001 From: Erik Marks <25517051+rekmarks@users.noreply.github.com> Date: Wed, 8 Apr 2026 11:00:42 -0700 Subject: [PATCH 2/3] chore(claude): Add changelog updating to pr skill --- .claude/skills/pr/SKILL.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/.claude/skills/pr/SKILL.md b/.claude/skills/pr/SKILL.md index 342047784d..74f54ba301 100644 --- a/.claude/skills/pr/SKILL.md +++ b/.claude/skills/pr/SKILL.md @@ -107,9 +107,15 @@ Otherwise, after all launched subagents complete: - Abort 4. If there are no blockers, briefly summarize the findings and proceed. -## Phase 4: Create the PR +## Phase 4: Update changelogs -5. Run `gh pr create` to create a pull request. The PR body should include: +**MANDATORY — DO NOT SKIP.** Each PR must update changelogs for all packages with consumer-facing changes. +Read the instructions in [`docs/contributing/updating-changelogs.md`](../../../docs/contributing/updating-changelogs.md) and follow them to the letter. +Commit the changes to the current branch with the commit message "docs: Update changelogs" before creating the PR. + +## Phase 5: Create the PR + +1. Run `gh pr create` to create a pull request. The PR body should include: - A brief narrative description of the PR - A summary of the changes (bullet points) @@ -117,4 +123,4 @@ Otherwise, after all launched subagents complete: **If this is a stacked PR**, add `--draft` to create it as a draft PR. -6. Return the PR URL and any relevant information. If a review was performed, include the review summary. +2. Return the PR URL and any relevant information. If a review was performed, include the review summary. From d4c00249f25f885170d459e1a9c9e684d463bacf Mon Sep 17 00:00:00 2001 From: Erik Marks <25517051+rekmarks@users.noreply.github.com> Date: Wed, 8 Apr 2026 11:01:49 -0700 Subject: [PATCH 3/3] chore(claude): Add standalone update-changelogs skill --- .claude/skills/update-changelogs/SKILL.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 .claude/skills/update-changelogs/SKILL.md diff --git a/.claude/skills/update-changelogs/SKILL.md b/.claude/skills/update-changelogs/SKILL.md new file mode 100644 index 0000000000..31ae5c7dce --- /dev/null +++ b/.claude/skills/update-changelogs/SKILL.md @@ -0,0 +1,10 @@ +--- +name: update-changelogs +description: Updates changelogs for all packages with consumer-facing changes. +--- + +When asked to update changelogs, follow these steps: + +1. Read the instructions in [`docs/contributing/updating-changelogs.md`](../../../docs/contributing/updating-changelogs.md) and follow them to the letter. +2. Commit the changes to the current branch with the commit message "docs: Update changelogs" before creating the PR. +3. Return the commit hash and the commit message.