Skip to content

Update CHANGELOG guidance in AGENTS.md - #80848

Closed
scruffian wants to merge 2 commits into
trunkfrom
update/changelog-guidance
Closed

scruffian wants to merge 2 commits into
trunkfrom
update/changelog-guidance

Conversation

@scruffian

Copy link
Copy Markdown
Contributor

What?

Clarifies the need for CHANGELOG entries in new PRs.

Why?

When reviewing PRs with an agent, it keeps flagging missing CHANGELOG updates, but we don't always require them, only if the changes are external facing.

How?

Updates to the docs.

Testing Instructions

Read the documentation and confirm you agree with it!

@scruffian scruffian self-assigned this Jul 29, 2026
@scruffian
scruffian requested a review from kevin940726 as a code owner July 29, 2026 16:00
@github-actions

github-actions Bot commented Jul 29, 2026 •

Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: scruffian <scruffian@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@github-actions

Copy link
Copy Markdown

Warning: Type of PR label mismatch

To merge this PR, it requires exactly 1 label indicating the type of PR. Other labels are optional and not being checked here.

  • Required label: Any label starting with [Type].
  • Labels found: .

Read more about Type labels in Gutenberg. Don't worry if you don't have the required permissions to add labels; the PR reviewer should be able to help with the task.

@github-actions github-actions Bot added the [Package] E2E Tests /packages/e2e-tests label Jul 29, 2026
@scruffian
scruffian force-pushed the update/changelog-guidance branch from b015000 to 0a7fb3b Compare July 29, 2026 16:00
@github-actions github-actions Bot removed the [Package] E2E Tests /packages/e2e-tests label Jul 29, 2026
@github-actions

Copy link
Copy Markdown

Size Change: 0 B

Total Size: 7.76 MB

compressed-size-action

@ciampo

ciampo commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

"all changes" vs "external changes" is something that we've discussed before with the rest of the @WordPress/gutenberg-components crew, let's make sure we're all aligned here

@scruffian

Copy link
Copy Markdown
Contributor Author

Also cc @ellatrix

Comment thread AGENTS.md
### Key Directories

- `/packages/` - JavaScript packages (each has README.md and CHANGELOG.md)
- `/packages/` - JavaScript packages (each has a `README.md` and `CHANGELOG.md`). Production package changes that affect external consumers require an entry in that package’s `CHANGELOG.md`. Consumer-visible changes include public API additions, removals, or behavior changes; changes observable through supported components or APIs; compatibility fixes; and changes to published package output. Do not add entries for tests, refactors, private APIs, or other internal implementation changes that have no effect on package consumers.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this affects how an agent should behave in /packages/ folder, I think the guidance could live in /packages/AGENTS.md so as not to bloat context for work it does outside that directory?

@aduth

aduth commented Jul 29, 2026 •

Copy link
Copy Markdown
Member

I don't really have strong feelings about this and am happy to go either way.

The way I think about each perspective:

  • Always including changelogs is simple, mechanical, and exhaustive. We might not always know what's relevant for our consumers. Organizing sections like discussed in Storybook: Upgrade to 10.5 #80692 (comment) could be an alternative to keep things organized in a way that the most relevant content is surfaced first and the consumer can use their own judgment on whether to skip some content of the changelog that they don't care about.
  • Applying judgment in changelogs keeps them entirely relevant and concise. In some ways it saves effort (not having to make the change, especially in a roundabout way after failing CI checks) and in others it introduces effort (in applying judgment about whether a note should be included). It also introduces more risk that changelog notes are skipped when they should in-fact be included.

@scruffian

Copy link
Copy Markdown
Contributor Author

Closing this as I prefer that we do have more changelogs!

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants