From 5156151b5203f58df28e9b87cbaffeb71140d137 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Mon, 11 May 2026 09:29:52 -0400 Subject: [PATCH 1/2] Design System: Add AGENTS guidance for changelogs --- packages/components/AGENTS.md | 10 ++++++++++ packages/theme/AGENTS.md | 8 ++++++++ packages/ui/AGENTS.md | 9 +++++++++ 3 files changed, 27 insertions(+) create mode 100644 packages/theme/AGENTS.md create mode 100644 packages/ui/AGENTS.md diff --git a/packages/components/AGENTS.md b/packages/components/AGENTS.md index ff2cad80eca2d4..41431329c99fbb 100644 --- a/packages/components/AGENTS.md +++ b/packages/components/AGENTS.md @@ -15,3 +15,13 @@ For adding validation, consider using the [Validated Form Components](./src/vali ## Storybook Don't forget to check a components's Storybook documentation for additional usage guidance. The Storybook links ([public base URL](https://wordpress.github.io/gutenberg/)) are also useful to present to a human when they are asking for help with a component. + +## Changelogs + +Add an entry to `CHANGELOG.md` for any change in this package. + +- Add the entry under `## Unreleased` at the top of the file. If that heading doesn't exist (i.e. the previous release header is at the top), add it. +- One entry per PR, not per commit. If the branch already has a bullet under `## Unreleased` for this PR, edit it to cover any follow-up commits rather than adding a second bullet. +- Pick the right sub-heading per the canonical guidance in [`packages/README.md`](../README.md#maintaining-changelogs) (`Breaking Changes`, `Deprecations`, `New Features`, `Enhancements`, `Bug Fixes`, `Internal`, etc.). +- When the change is scoped to one or a small number of components, prefix the bullet with the component name(s) in backticks — e.g. `` `Button`: Fix … ``. Omit the prefix for broad cross-cutting changes (build config, shared utilities, repo-wide refactors). +- Once the PR exists, append `([#NNNNN](https://github.com/WordPress/gutenberg/pull/NNNNN))` to the end of the bullet. If the PR number isn't known yet, omit the parenthetical. diff --git a/packages/theme/AGENTS.md b/packages/theme/AGENTS.md new file mode 100644 index 00000000000000..c29e5c3883ec91 --- /dev/null +++ b/packages/theme/AGENTS.md @@ -0,0 +1,8 @@ +## Changelogs + +Add an entry to `CHANGELOG.md` for any change in this package. + +- Add the entry under `## Unreleased` at the top of the file. If that heading doesn't exist (i.e. the previous release header is at the top), add it. +- One entry per PR, not per commit. If the branch already has a bullet under `## Unreleased` for this PR, edit it to cover any follow-up commits rather than adding a second bullet. +- Pick the right sub-heading per the canonical guidance in [`packages/README.md`](../README.md#maintaining-changelogs) (`Breaking Changes`, `Deprecations`, `New Features`, `Enhancements`, `Bug Fixes`, `Internal`, etc.). +- Once the PR exists, append `([#NNNNN](https://github.com/WordPress/gutenberg/pull/NNNNN))` to the end of the bullet. If the PR number isn't known yet, omit the parenthetical. diff --git a/packages/ui/AGENTS.md b/packages/ui/AGENTS.md new file mode 100644 index 00000000000000..72ac1394ecc3e0 --- /dev/null +++ b/packages/ui/AGENTS.md @@ -0,0 +1,9 @@ +## Changelogs + +Add an entry to `CHANGELOG.md` for any change in this package. + +- Add the entry under `## Unreleased` at the top of the file. If that heading doesn't exist (i.e. the previous release header is at the top), add it. +- One entry per PR, not per commit. If the branch already has a bullet under `## Unreleased` for this PR, edit it to cover any follow-up commits rather than adding a second bullet. +- Pick the right sub-heading per the canonical guidance in [`packages/README.md`](../README.md#maintaining-changelogs) (`Breaking Changes`, `Deprecations`, `New Features`, `Enhancements`, `Bug Fixes`, `Internal`, etc.). +- When the change is scoped to one or a small number of components, prefix the bullet with the component name(s) in backticks — e.g. `` `Select`: Fix … ``. Omit the prefix for broad cross-cutting changes (build config, shared utilities, repo-wide refactors). +- Once the PR exists, append `([#NNNNN](https://github.com/WordPress/gutenberg/pull/NNNNN))` to the end of the bullet. If the PR number isn't known yet, omit the parenthetical. From 4fae4f15b2c8d00620eee4c07c350b32eb3ace95 Mon Sep 17 00:00:00 2001 From: Andrew Duthie Date: Mon, 11 May 2026 09:50:29 -0400 Subject: [PATCH 2/2] Add CLAUDE.md mirror reference to AGENTS guidance --- packages/theme/CLAUDE.md | 1 + packages/ui/CLAUDE.md | 1 + 2 files changed, 2 insertions(+) create mode 100644 packages/theme/CLAUDE.md create mode 100644 packages/ui/CLAUDE.md diff --git a/packages/theme/CLAUDE.md b/packages/theme/CLAUDE.md new file mode 100644 index 00000000000000..43c994c2d3617f --- /dev/null +++ b/packages/theme/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/packages/ui/CLAUDE.md b/packages/ui/CLAUDE.md new file mode 100644 index 00000000000000..43c994c2d3617f --- /dev/null +++ b/packages/ui/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md