Commit 670e47d975a for woocommerce
commit 670e47d975a1030e9899c8f8193ece454d3427a4
Author: Vlad Olaru <vlad.olaru@automattic.com>
Date: Tue Sep 22 19:58:02 2026 +0300
[ai docs] Give changelog entries their authoring rules where agents actually read them (#68899)
* docs: Give changelog entries their authoring rules in AGENTS.md
The Changelog Entries section covered only mechanics: which command to
run, and when. What to actually write was documented elsewhere, in the
woocommerce-git-commit skill, which an agent loads only when it asks to
commit. By then the entry is usually already written, so the rules
arrived after the decision they govern. AGENTS.md is in context for
every session, since CLAUDE.md is a single @AGENTS.md include, so the
rules belong here.
Both length targets come from the shipped record rather than taste.
Across all 14,435 published bodies in changelog.txt the median is 68
characters and the 90th percentile is 132. Releases 9.0 through 10.6,
eighteen in a row, held a median of 60 to 80; from 10.7 onward the median
sits near 105, the 90th percentile runs past 200, and the entries
pending right now are longer still. About 120 characters clears the
stable era's 90th percentile and already covers 87% of everything ever
published, so it restores the earlier norm rather than inventing one.
The same measurement on the 195 `Comment:` values gives a median of 104,
with three quarters of them longer than the example the skill itself
offers. Those never ship and are read only by reviewers, so 100
characters is enough for the area and the kind of change.
Record the review bar as well: since the move to the Jetpack
Changelogger the entry is reviewed as part of the change, and a
reviewer asks for changes on a weak entry as they would on weak code.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: Point the changelog skill at the authoring rules in AGENTS.md
The skill's Changelog Entry Files section documents the file format and
is loaded only when an agent invokes it to commit. The rules about what
to write, who reads each field, and how long it should be now live in
the repository root AGENTS.md, which every session reads. Add a pointer
so the two stay linked without duplicating a character target that
would drift.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
* docs: Sharpen the changelog authoring rules from review feedback
The section opened by asserting that entries are reviewed like code,
which tells an agent the stakes but not what to do. Lead with the
instruction instead — write for whoever reads the field — and keep the
review bar as the second sentence, since it is what makes a weak entry
worth a reviewer's pushback.
Two other refinements from the same review:
The `Comment:` guidance named the area and kind of change but dropped
the reason the field exists. The woocommerce-git-commit skill defines
it as the place to explain why there is no user-facing line, so say
that here too and extend the example to match the skill's shape. Of the
108 `Comment:` values pending in the tree only six carry such a clause,
so the rule is worth stating plainly rather than leaving to inference.
"Go longer only when the change genuinely needs it" was circular. Name
the three things that earn the extra characters: the affected behavior,
an important condition, or a required action.
Refs #68899
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: Add a negative changelog example for the body vs Comment choice
Both examples in the section showed a well-formed entry. Neither showed
the mistake the section exists to prevent: choosing Type: dev with a
body when the change ships nothing. A body always publishes, so the
entry reaches the plugin's wordpress.org page as a Dev line, while
Comment: suppresses it. Nothing in the positive examples makes that
difference visible, since both of them are correct by construction.
The failure is real rather than hypothetical. Pulling the readme.txt
that wordpress.org served for the last two minor releases, 11.1.0
published 52 Dev lines of which 28 were test or tooling only, and
11.0.0 published 34 of which 21 were. The release currently in trunk
carries 9 more. They are not wrong to merchants so much as they dilute
the developer advisories they sit beside, which is the part a reader
of that page is there for.
Keep the example free of a version number. This file is loaded in
every session, so a figure that ages turns into a correction someone
has to make later, and the guardrail works without one.
Refs #68899
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: Add a negative changelog example for length and detail level
The section gave a character target but nothing to recognise when a
body misses on content rather than count. The two failures look
different and the number only catches one of them.
Both examples are drawn from entries that shipped to wordpress.org. A
short body can still be wrong: naming a method tells a reader what was
edited, not what now happens, and no merchant can act on it. A long
body fails from the other end, and the worst published case runs past
500 characters because it opens on two filter names before reaching
what they let a plugin do. Pairing the short case with its rewrite
shows the repair rather than restating the limit, which is the part a
character count cannot teach.
Keep this one free of a version number too, for the reason the
previous example is.
Refs #68899
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: Use a constructed method name in the changelog example
The example quoted a real published entry. It was a common shape
rather than anyone's blunder, but the file is public and permanent,
and the line stayed traceable to the pull request that shipped it. An
author does not need their entry held up as the wrong way in the
document every contributor reads.
Swap in a constructed pair that teaches the same thing. The names are
unused anywhere in the repository, so nothing reads as an API that
callers could reach for, and they stay clear of wc_reduce_stock_levels
and its neighbours so no one mistakes the example for a real function
they half remember. The bad version is 79 characters and the rewrite
is 74, both inside the limit, which is the point: the miss is content,
not count, and a character target cannot catch it.
This also corrects the previous commit, which said both examples came
from entries shipped to wordpress.org. That is now true only of the
first one.
Refs #68899
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: Frame the changelog example around the public changelog
The example pointed at the plugin's wordpress.org page. That is one
surface rather than the rule, and it invited questions the line should
not have to answer, since that page carries a single release at a time
and links out for the rest. An author deciding between a body and a
Comment does not need any of that.
Name the public changelog instead. It is the thing the entry reaches,
it does not change when the release or the surface does, and it
matches the Body bullet directly above, which already points at the
same place.
Refs #68899
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
diff --git a/.ai/skills/woocommerce-git-commit/SKILL.md b/.ai/skills/woocommerce-git-commit/SKILL.md
index 2aa1900be4b..f1c7564c07c 100644
--- a/.ai/skills/woocommerce-git-commit/SKILL.md
+++ b/.ai/skills/woocommerce-git-commit/SKILL.md
@@ -111,6 +111,8 @@ Type: dev
Comment: Remove real sleep() calls from PHP unit tests; no production change.
```
+What to actually write in each field — who reads it, the length targets, and the review bar — is in the Changelog Entries section of the repository root `AGENTS.md`.
+
Do not confuse `Comment:` with the pull request template's "Comment required below" field. That one belongs to the PR form and is unrelated to the changelog file.
Changes that touch no package (for example `.ai/skills/` or `AGENTS.md`) need no entry at all.
diff --git a/AGENTS.md b/AGENTS.md
index fad8d86c886..90b1dc2247d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -130,6 +130,17 @@ pnpm --filter=@woocommerce/plugin-woocommerce changelog add
This command prompts for the change type and description. Run it once per affected package before creating any PR.
+**Writing the entry.** Write for whoever reads the field: merchants read the body, reviewers read the comment. A reviewer asks for changes on a weak entry as they would on weak code.
+
+- **Body**: one merchant-facing sentence, about 120 characters or fewer. It ships verbatim to the public `changelog.txt`, so say what changed for merchants, not how. No issue or PR refs; the tooling appends the PR link. Example: `Restore the "Browse store" link on the empty cart page.`
+- **`Comment:`** (`Type: dev`, no body): about 100 characters or fewer naming the area and kind of change, not the implementation, and making clear why nothing ships to merchants. Only reviewers read it. Example: `Improve system status and payment gateway REST API tests; no production change.`
+
+Not this: `Type: dev` with the body `Add unit tests covering customer session fallbacks.` — a body always ships, so an internal-only change lands in the public changelog as a `Dev -` line. Only `Comment:` keeps it out of the release notes.
+
+Not this either: `Make WC_Shipping_Cache::refresh_package_rates() run after cart contents change.` — a method name is not an outcome. Say what it does: `Show updated shipping costs after the cart changes, instead of stale ones.` A body that opens on two filter names and runs past 500 characters fails the same way, from the other end.
+
+Use more characters when they identify the affected behavior, an important condition, or a required action. The `woocommerce-git-commit` skill has the file format.
+
### Pull Request Template
When creating PRs, **always use the template** from `.github/PULL_REQUEST_TEMPLATE.md`. Key sections: