Repository navigation
Package changelogs: Improve consistency and prevent future drift #81341
Description
Follow-up to the #81331 discussion.
The goal is to make package changelogs useful to consumers and prevent new drift. This issue now separates work shipped on trunk from remaining implementation and policy decisions. Checked items describe completed work only; proposals remain unchecked.
Reassessed on 2026-10-01 against trunk 0771c7a7cf35. The current source check covers 124 package changelogs and schemas/CHANGELOG.md. Generated root changelog.txt remains out of scope. Historical npm-wide figures below have not been rerun and must not be read as current counts.
Work shipped since the original audit
- #83043 documented the entry format and ordered categories, added
npm run lint:changelogsand validator tests, split entry-presence checks from structure validation, and repaired selected current entries. - #83577 expanded the optional presence matrix to 35 packages, including published tooling and configuration packages.
- #83618 refined presence-check exclusions for documentation, stories, tests, and development configuration. #82069 had already made changelog-only changes skip the presence check.
- #82089 made npm publication verification and recovery resumable, including registry identity, dist-tags, remote branches/tags, and finalization/backports.
- #81658 backfilled ESLint Plugin changelog entries, including two candidates from this audit.
1. Release sections and metadata
Publication recovery has improved, but it does not establish a complete changelog ledger or repair historical omissions.
- Verify target npm versions, registry
gitHead, and dist-tags during publication/recovery. Release: Make npm publication verification resumable #82089. - Push and verify release branches and package tags, preserving prepared state so interrupted publication can resume. Release: Make npm publication verification resumable #82089.
- Make finalization and changelog/version-commit backports recoverable for
latestand bugfix releases. Release: Make npm publication verification resumable #82089. - Decide whether changelogs list every published version or only releases with consumer-facing changes.
- Extend release verification to compare expected package versions with changelog release headings, in addition to registry and Git metadata.
- Define changelog handling for WordPress-targeted and branch-only releases.
updatePackages()still explicitly skips changelog processing for WordPress-targeted releases. - Re-audit supported-branch gaps and repair those with reliable source data; obtain release-owner review for package paths absent from their target branches.
- Define how empty releases are represented, for example
_No consumer-facing changes._if a complete ledger is intended. - Validate release versions, dates, duplicates, and ordering under the agreed release policy.
Source: package release implementation.
Original release audit, retained as historical evidence
The original audit used commit 8181ec4897c3, 125 package changelogs, and live npm metadata for 120 public packages. At that time:
- Trunk and npm
latestmetadata were consistent. - Across 1,255 npm
wp-X.Ydist-tag checks, 1,224 package versions had a matching branch manifest but no matching release heading. - Thirteen package/tag pairs pointed to branches without the package path.
- Across npm history, 8,963 of 19,710 stable versions had no matching heading on trunk. This included old, branch-only, security, and pre-convention releases; it is not a request to add them all by hand.
- There were 9,060 empty published-version sections, one duplicate release, six subsection headings using
##, seven missing dates, one nonstandard date, and three missing maintenance comments. - Block Library: Restore 8.19.19 release metadata #81331 repaired one release-metadata example.
These registry-wide and historical structure counts have not been refreshed. They establish the original scope, not today's release health.
2. Missing entries and source links
The reassessment searched each candidate's entire named changelog, including published releases. Of the original 52 package-entry candidates, three have implementing PR links and 49 still lack them. A missing link alone does not establish that a separate entry is needed.
- Document ESLint Plugin Components: Deprecate Animate #80931 and Components: Deprecate Surface #80943 in one consumer-focused entry. Added in UI: Mark Input-related components as recommended #81658.
- Resolve the Element Element: Make the package importable in React 19 #80053 audit candidate: its entry was already present under
8.3.0in the original snapshot. This is a correction to the audit, not a subsequent changelog fix. - Review the remaining 49 package-entry candidates for consumer impact, existing consolidated descriptions, and the correct release section.
- Consolidate related changes where one result-focused entry is more useful than several implementation notes.
- Repair remaining missing, issue-only, and malformed source links. Older candidates may now belong to published sections rather than
Unreleased. - Add missing schema entries after confirming the intended schema changelog policy.
Remaining candidates and source-link repairs
The original audit compared history after the 2026-07-29 package release with Unreleased. It reported 65 commits and 110 public-package touches without matching PR links after excluding private packages and mechanical migrations. Those are historical figures. The remaining candidate list is:
- Block Editor: #80813, #80824, #77151, #80891, #80994, #81076, #81129, #81111, #81138, #81159, #81155, #80027, #81277, and #81288. The List View performance PRs should probably become one result-focused entry.
- Block Library: #80844, #77151, #80912, #80724, #81111, #81138, #81159, #81018, #81130, #81142, #81181, #80027, #81184, and #81177.
- Schemas: #80173, #81209, #81253, and #81309.
- Editor: #81020, #80539, #81064, #76470, and #79836.
- Core Data: #80539, #79836, and #81318.
- Other packages: Sync #80539; Rich Text #80994; Scripts #81141; Base Styles #81145; Blocks #80027; Format Library #81271; and Edit Post, Edit Site, and Editor #79934.
A file touch is not proof that every affected package needs a separate entry. Package owners should confirm the final list and prefer useful consumer descriptions.
The following implementing PR links are still absent from package changelogs: #81250, #79934, #81002, #81193, #81307, #81206, #80725, and #81130. The original audit identified the first five as missing source links and the last three as implementing PRs for issue-linked entries. Review the descriptions before deciding whether to add or consolidate entries.
The malformed outer parentheses for #80929 in Block Editor and #79792 in WP Build also remain. schemas/CHANGELOG.md is unchanged from the original snapshot and still has no versioned release ledger.
3. Documentation and CI coverage
Structure validation and entry presence are separate checks. A changed package changelog receives structure validation regardless of the presence allowlist. Presence checks remain optional and cover 35 hardcoded packages.
- Document an entry template with an implementing PR link and terminal period. Automated Testing: Document and validate expected changelog structure #83043.
- Align entry guidance with optional checks: prefer consumer-facing entries; trivial and non-consumer changes may omit them. Automated Testing: Document and validate expected changelog structure #83043.
- Validate changed
packages/*/CHANGELOG.mdfiles regardless of which package owns them. Automated Testing: Document and validate expected changelog structure #83043. - Expand the presence matrix from 16 to 35 packages. CI: Check CHANGELOG presence for published tooling and config packages #83577.
- Skip presence checks for changelog-only changes and refine exclusions for documentation, tests, stories, and development configuration. CI: Skip the package CHANGELOG check when only the CHANGELOG changed #82069 and Changelog validator: ignore markdown & configs d46223 #83618.
- Correct the original duplicate-
PACKAGE_PATHfinding: the original snapshot and current workflow declare it in separate step-levelenvblocks. There is no duplicate key within one block to fix. - Decide whether presence checks should cover every public production package and whether an explicit no-consumer-change decision should be required. The current optional-check policy does not implement that proposal.
- Replace duplicated hardcoded package lists with discovery based on the agreed coverage policy.
- Include
schemas/CHANGELOG.mdin local discovery and CI, with a documented schema-specific format if needed. - Document exceptions and source-reference rules for direct commits, security work, backports, branch-only changes, private packages, multiple PRs, and consolidated entries.
Sources: maintaining changelogs and CI workflow.
4. Validation and auto-fixes
- Add
npm run lint:changelogs, with automatic discovery of package changelogs when no paths are supplied. Automated Testing: Document and validate expected changelog structure #83043. - Support explicit paths and PR-aware validation through
--prand--require-pr. Automated Testing: Document and validate expected changelog structure #83043. - Validate
Unreleasedsubsection levels, allowed names, ordering, and duplicate subsections. Automated Testing: Document and validate expected changelog structure #83043. - Require a numeric Gutenberg PR link for each recognized top-level entry; reject entries whose only source is an issue link. Automated Testing: Document and validate expected changelog structure #83043.
- Detect a current-PR link placed only in a published release; require its presence in
Unreleasedwhen--require-pris used. Automated Testing: Document and validate expected changelog structure #83043. - Add automated tests for the validator's implemented rules. Automated Testing: Document and validate expected changelog structure #83043.
- Add
--fixfor agreed, unambiguous syntax corrections. - Add release validation for the policy in section 1.
- Define staged enforcement and historical baselines before expanding checks beyond
Unreleased. - Decide when missing maintenance comments and missing
Unreleasedheadings should fail validation. A missingUnreleasedsection currently passes unless--require-pror PR-placement checking establishes an error. - Add regression coverage for the remaining validation gaps as each rule is implemented.
Verified scope and limitations of the current validator
The validator passed all 124 package changelogs in the reassessed snapshot. That result only verifies its implemented rules. It does not establish complete entries, historical consistency, or release-metadata parity.
Focused probes confirmed that it accepts:
- Different numeric PR labels and URL targets, such as
[#123](https://github.com/WordPress/gutenberg/pull/456). - An entry lacking outer parentheses and terminal punctuation.
- A changelog without
Unreleasedwhen no PR requirement is supplied. - Duplicate published release headings.
It rejects an unknown Features subsection and a recognized entry with only an issue link. Its PR-link regex checks syntax, not whether the PR exists or implements the described change.
The default command discovers only packages/*/CHANGELOG.md; CI also selects only package changelogs. schemas/CHANGELOG.md is excluded from both. For a selected file, validation covers its entire Unreleased section, not just added or modified lines. Published sections are otherwise outside structural validation, apart from current-PR placement checking.
Safe auto-fix candidates include agreed heading aliases, section ordering, duplicate subsection consolidation, spacing, matching PR labels, and canonical suffixes. Release-date repairs require known source data. Spelling fixes must avoid code spans and quoted misspellings. Semantic classification, consumer usefulness, affected-package coverage, consolidation, and security wording remain review responsibilities.
Source: validator.
5. Section names and categories
- Keep
New FeaturesandEnhancementsdistinct. Automated Testing: Document and validate expected changelog structure #83043. - Document and enforce the same ordered category list for
Unreleased. Automated Testing: Document and validate expected changelog structure #83043. - Repair selected current category and duplicate-subsection problems, including Block Editor's duplicate
Internalheading. Automated Testing: Document and validate expected changelog structure #83043. - Normalize safe historical naming variants separately from semantic reclassification.
- Review entries whose category conflicts with their consumer effect, including regressions, published types, and performance changes.
- Document safe security-entry classification.
Securitywas part of the original proposal but is not accepted by the shipped validator.
The shipped order is Stable Release, Breaking Changes, New Features, Enhancements, Deprecations, Bug Fixes, Internal, Documentation. This replaces the earlier proposed order in this issue. New APIs, Code Quality, Experimental, TypeScript, and Performance are not allowed Unreleased headings.
The release parser still accepts some older heading prefixes, including New API, but the validator's narrower documented list prevents those names in validated Unreleased sections. Classification must follow consumer impact, not keyword-based auto-fixes.
Historical category audit
The original snapshot had 2,471 subsection headings using 24 names, including 197 headings outside the originally proposed canonical set in 52 files. Sixty were simple naming variants; 137 used additional categories. There were 29 repeated subsection groups in 11 files.
These counts have not been refreshed against the shipped taxonomy. In particular, categories such as Documentation must now be judged against the documented current list, not treated as violations merely because the original audit listed them separately.
Suggested semantic review remains: classify performance changes as enhancements or regression fixes; classify published-type changes by their consumer effect; omit or use Internal for appropriate non-consumer work; describe experimental status in the entry instead of using an Experimental heading.
6. Entry format and spelling
- Adopt and document a trailing implementing PR link and terminal period. Automated Testing: Document and validate expected changelog structure #83043.
- Enforce numeric PR-link syntax for recognized entries in
Unreleased. Automated Testing: Document and validate expected changelog structure #83043. - Require PR labels to match their URL targets.
- Enforce the documented link placement, outer parentheses, and terminal punctuation, with defined handling for multiple PRs and nested lists.
- Define and enforce blank-line and bullet-spacing conventions where existing formatting tools do not cover them.
- Repair broken and mismatched historical PR links.
- Fix confirmed spelling and wording errors outside code spans and quoted examples.
The current snapshot contains 101 mismatched numeric PR labels and URL targets across package changelogs; 90 are the repeated #31270 label pointing to PR #61930. These are refreshed counts, compared with 103 and 92 in the original audit. The malformed suffixes for #80929 and #79792 remain.
Original formatting evidence and entry example
### Bug Fixes
- `Component`: Fix the consumer-visible problem and state the resulting behavior ([#12345](https://github.com/WordPress/gutenberg/pull/12345)).Describe public behavior, API, compatibility, or required consumer action. The imperative wording above is the original proposal; the shipped documentation specifies links and punctuation but does not prescribe that verb tense.
The original audit also reported 890 noncanonical PR suffixes, 16 broken parenthesized links, 18 bullet-spacing differences, 86 double-blank-line runs, and ten sibling-entry pairs with an extra blank line. These counts have not been refreshed.
Original spelling candidates included coniguration, intial, DatViews, sizs, cliking, chared, stings, othr, autocomple, ComoboboxControl, the the, and 0.8 .0. Recheck each occurrence before editing; quoted misspellings and code identifiers must be preserved.
7. Longer-term authoring workflow
Direct changelog edits remain the shipped workflow. Structured per-PR fragments are still a proposal and need not block incremental validator improvements.
- Decide whether to pursue fragments as a separate follow-up.
- If adopted, define package, category, consumer summary, and optional consolidation metadata.
- Let CI supply the PR number automatically.
- Support an explicit no-consumer-change decision without necessarily publishing it as an entry.
- Compile canonical changelog sections on the correct release branch, including agreed backport handling.
Remaining decisions and sequencing
The entry template, current category list, and optional entry guidance have shipped. They no longer need to be treated as prerequisites for all implementation.
- Agree on coverage and exceptions before widening presence checks or requiring explicit no-consumer-change decisions.
- Agree on complete-ledger and empty-release policy before expanding release verification or repairing branch-only history.
- Extend the existing validator for confirmed syntax gaps, keeping mechanical fixes separate from semantic review.
- Review the remaining entry candidates and historical debt with package owners; refresh old audit counts before planning bulk cleanup.
- Treat fragments as a separate authoring-workflow decision.
Activity
aduth commentedon Oct 1, 2026
There's a lot here, but I imagine that a lot of this will have improved by #83043.
ciampo commentedon Oct 1, 2026
Good point, I tweaed the issue description and tried to check all points that I feel have been addressed already
talldan commentedon Oct 7, 2026
I'm supportive of required package changelogs, but the constant merge conflicts from the current workflow are too much friction.
I think it's something that needs to be solved sooner rather than later. It is just not at all pleasant to work on the project while it's like this. Taking into account how time each contributor spends solving conflicts, it's time that could be better spent elsewhere.
edit: Just to add, I am personally happy to work on improving it (e.g. switching to changelog fragments), but at the same time don't want to duplicate or cause issues with other work on changelogs.
ciampo commentedon Oct 7, 2026
I'm in favor of using fragments, but I wonder if this requires some form of consensus before moving forward. Should we just cc
WordPress/gutenberg-core?talldan commentedon Oct 8, 2026
There's a past discussion on the subject here in slack - https://wordpress.slack.com/archives/C02QB2JS7/p1718178158242679.
ciampo commentedon Oct 8, 2026
I guess we have consenus to at least propoase an approach in a PR. @talldan , are you going to own this initial exploration? In the past I had personally proposed https://github.com/changesets/changesets, but I don't have a strong preference.
talldan commentedon Oct 13, 2026
I'm happy to look into it. The third party tools that came up in my search were:
We'll need to think about rollout too. Maybe we experiment with one or two packages first? I think whatever we do, and whichever tool we use we shouldn't disregard how well it works in a monorepo.
ciampo commentedon Oct 13, 2026
I'd shortlist Changesets and Changie for the pilot. Changesets looks strongest for npm monorepo releases; Changie seems closer to fixing changelog conflicts while keeping our release process.
I tasked an agent to prepare a quick comparison table
Checked on 13 October 2026; release months refer to 2026. Since 15 July, Changesets and Towncrier show broader contributor activity; Changie relies mainly on its creator. I'd weigh that risk without ruling it out. Stars alone don't establish reliability or future support, as Towncrier's established adoption illustrates.
The main catch is preserving our release rules: categories determine version bumps, with release-wide minimums and special handling for
0.xpromotion. Changesets would need integration here.I'd test both with a change spanning two packages, different version bumps, a backport, and a release with no new entry. I'd also check fragment readability and migration. This is based on docs and source; I'd choose after the pilot.
Other options worth considering
talldan commentedon Oct 15, 2026
I did some diving into this today. I lean towards trying out Changie. It seems to fit better with our existing workflows. It's more of a minimal tool, so:
Some shortcomings:
So far I think we can workaround the shortcomings. I think we could propose/work on some upstream changes too that are mutually beneficial.
I looked at changesets too. It does have some cool features, but I think it's too much of a shift. It requires only 'major', 'minor', and 'patch' kinds of changes (example - https://github.com/changesets/changesets/blob/main/packages/cli/CHANGELOG.md), and it's more deeply integrated into the release process.