Repository navigation
Design System: Add AGENTS guidance for changelogs #78166
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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. | ||
|
Member
There was a problem hiding this comment. This is not true, some changes (such as this PR!) don't justify a changelog entry. Maybe "for any change that may affect consumers"? Unit test and documentation changes are usually irrelevant.
Member
Author
There was a problem hiding this comment.
In fact, the original AI suggestion was to include "user-visible changes" only. I could get on board with that personally, though I think we need to be consistent. In particular, I seem to recall some conversations (and observations like in #77319) where we have changelogs for every pull request, even mostly "internal" changes. I also noticed in #78169 that our CI testing file patterns exclude certain files, so whatever we decide should be in sync with how we test.
Contributor
There was a problem hiding this comment. For me, it's important to establish a rule that can be inferred/applied objectively. As far as we have clear guidelines for when to add and not to add an entry, I'm on board
Member
There was a problem hiding this comment. My only concern with the "user-visible changes" phrasing is clarifying who users are. In the case of
Contributor
There was a problem hiding this comment. In my opinion, the primary audience for CHANGELOGs is developers who are either consuming a package or working on that package directly |
||
|
|
||
| - 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.). | ||
|
Member
There was a problem hiding this comment. What I sometimes observe is the agent picking a heading that clearly doesn't match the "Type" tag I've added to the PR. The most important distinction is between an enhancement, bug fix, and breaking change. Maybe instruct the agent to prioritize headings to match the author intent if enhancement, bug fix, or breaking change tags have already been added to the PR?
Member
Author
There was a problem hiding this comment.
Yeah, that's a good idea 👍 Though it only works if a pull request is already opened by the time an agent is adding the changelog. And my expectation is that after this guidance, it'll be a lot more proactive about creating the changelog as part of the initial change (i.e. before the pull request). |
||
| - 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. | ||
|
Member
There was a problem hiding this comment.
Not sure how this will work in practice… The changelog is not going to be complete until the PR number is filled out. Is it possible to make the agent follow up with it? Personally, I only ask it to add a changelog after the PR is created, since that saves a round trip.
Member
Author
There was a problem hiding this comment.
It would be nice, but it's not what I'd expect personally. And I'm not sure that we could automate this. The phrasing here is kinda confusing, but the way I was thinking of it is:
The original proposal created by the agent mentioned leaving a " Maybe a simple change here is replacing "Once" with "If" ?
I can see how that workflow might work well, but I'm not really sure how we'd codify that in the agent guidance. Also, does it really save a round trip? It's two commits either way, right? I'd rather run the risk of a changelog entry not including its PR link than not having one at all. Honestly, I wish we could find some way to automate this PR link and not have it be something that contributors have to think about. For example, a GitHub Actions workflow that automatically commits the PR number into an existing changelog entry.
Contributor
There was a problem hiding this comment. I personally have my agent do it as part of "create a PR" task — it creates the CHANGELOG entry with a placeholder PR number, pushes to origin, inspects the PR number, amends the CHANGELOG and pushes again
Member
Author
There was a problem hiding this comment.
Maybe we can support this workflow through this file? Not necessarily saying that someone has to adopt this workflow for publishing a pull request, but if they're already using an agent to publish the pull request anyways, try to have it follow this procedure. |
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| @AGENTS.md |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| @AGENTS.md |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we just have generic changelog instructions at
packages/AGENTS.mdroot and refer to that file from here?So:
packages/components/AGENTS.mdinstructs to add changelog always, but refers to parent agent file for more info.packages/AGENTS.mdhas instructions on how to add changelog entries.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, I think you're right. I was a bit conservative with which package to apply this to, and already included some references to existing documentation (e.g. bullet about "canonical guidance in
packages/README.md"), but re-reading many of these points, they could apply to any changelog authoring in any package, so would make sense inpackages/AGENTS.mdand/or enhancing existing changelog guidance inpackages/README.md.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I haven't got around to updating this yet, but @jeryj added a note to the root
AGENTS.mdto this effect. Though I think your original suggestion ofpackages/AGENTS.mdmakes sense and I left a post-merge review comment.