Skip to content

Changelogs: trial using changie for managing changelogs in Components and UI packages - #85369

Draft
talldan wants to merge 46 commits into
trunkfrom
add/changie-for-changelogs
Draft

talldan wants to merge 46 commits into
trunkfrom
add/changie-for-changelogs

Conversation

@talldan

@talldan talldan commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Part of #81341

Note

Not for merging right now, especially with the WordPress beta happening. Lets discuss when the right time will be.

It may also be best to split this PR up - one for the tool updates, then PRs for the actual package migrations. For now this PR demonstrates the changes, but it's a lot of files, though it's mostly the individual version files.

What?

This PR demonstrates using changie to manage changelogs in the Components and UI packages. The proposal would be to gradually migrate all packages to it.

Changie is a command line tool that creates changelog entries as individual files (fragments), it then offers commands for compiling those entries into a final changelog. Changie is very configurable, so the final changelog output is exactly the same as before.

Why?

The main benefit of individual files for changelog entries is that there are no longer merge conflicts on feature branches when rebasing or merging in changes from trunk.

How? (generated with AI)

  • Added Changie and configured it at the repository root:
    • Pinned changie and added .changie.yaml to define standard categories (Breaking Changes, Enhancements, Bug Fixes, etc.), prompt questions (asking for the PR number), and output formatting.
    • Opting in is controlled per package via the projects list in .changie.yaml. We’re piloting this on @wordpress/components and @wordpress/ui.
  • Created the @wordpress/changelog-tools workspace (tools/changelogs):
    • Houses the scripts and libraries that bridge Changie with Gutenberg's existing workflows and release tools.
  • Added contributor commands:
    • npm run changelog:add: Interactively prompts for the package, change type, PR number, and description, writing an independent .yaml fragment file into .changes/unreleased/.
    • npm run changelog:preview -- : Dry-runs the compilation and displays what the unreleased notes for that package will look like in markdown.
    • npm run changelog:promote-stable -- : A dedicated tool with safety checks to create a Stable Release fragment only for 0.x packages ready to bump to 1.0.0 (keeping Stable Release out of routine PR menus).
  • Built migration tooling for maintainers:
    • npm run changelog:migrate -- : Splits an existing package's CHANGELOG.md into historical version markdown files under .changes// and unreleased YAML fragments, replacing the changelog with a clean header stub.
    • Added an --update flag (npm run changelog:migrate -- --update) so maintainers can refresh a migration branch when it falls behind trunk without resolving manual merge conflicts.
    • Added a --rollback option if a maintainer ever needs to reverse a migration back to a traditional CHANGELOG.md.
  • Integrated with the package release automation (release-cli):
    • Updated tools/release/commands/packages.js to read unreleased Changie fragments for version bump calculations, and automatically execute changie batch and changie merge when publishing packages.
  • Updated CI checks and linting:
    • Updated the GitHub Actions workflow (check-package-changelogs.yml) and npm run lint:changelogs to check for .yaml fragments instead of edits to CHANGELOG.md when an opted-in package is touched in a PR.
  • Added an AI Agent Skill & updated documentation:
    • Added a dedicated .agents/skills/package-changelog skill so coding agents know whether to write YAML fragments or edit CHANGELOG.md.
  • Updated packages/README.md, docs/contributors/code/managing-packages.md, and the release guides with instructions for contributors and maintainers.

Testing Instructions

Add a changelog entry

  1. Checkout this branch.
  2. Run npm run changelog:add.
  3. Follow the interactive prompts.
  4. Run git status / git diff — observe that an independent .yaml fragment was created under .changes/unreleased/.

Preview unreleased changes for a package

  1. Run npm run changelog:preview -- components or npm run changelog:preview -- ui to output the compiled unreleased notes for that package. Useful for verifying that your entry renders and formats correctly.

Promote a package to a stable release

  1. Run npm run changelog:promote-stable -- ui.
  2. Observe that a changelog fragment with kind Stable Release was created.
  3. Test guardrail: run npm run changelog:promote-stable -- components and verify that it rejects the promotion because @wordpress/components is already >= 1.0.0.

*Note: There is a separate command for stable release because it is usually a one-time occurence for a package, there's extra validation to prevent multiple stable releases in a package. This also keeps "Stable Release" from cluttering "Kinds" when a contributor runs the regular npm run changelog:add command.

Migrate a package to changie

  1. Create a branch: git checkout -b update/block-editor-changelogs-to-changie.
  2. Test dry-run: npm run changelog:migrate -- block-editor --dry-run to inspect version counts.
  3. Run migration: npm run changelog:migrate -- block-editor.
  4. Run git status — observe that .yaml fragments were created for all unreleased entries, past versions were split into .changes/block-editor/*.md, and packages/block-editor/CHANGELOG.md had its "Unreleased" section removed.

Updating an in-progress migration

If a migration branch falls behind trunk there's a chance new old-style changelog entries were added on trunk. The migration will need to be updated:

  1. Rebase on trunk: git pull --rebase origin trunk.
  2. If there is a merge conflict on CHANGELOG.md, keep trunk's version:
    git checkout origin/trunk -- packages/block-editor/CHANGELOG.md
  3. Update the migration: npm run changelog:migrate -- block-editor --update.
  4. Run git status — verify that previous fragments were refreshed and new entries from trunk were converted to fragments.

Rolling back a migration

If a package ever needs to be reverted back to traditional manual CHANGELOG.md maintenance:

  1. Run rollback: npm run changelog:migrate -- block-editor --rollback
  2. Run git status — observe that:
    • packages/block-editor/CHANGELOG.md was restored with its full version history and any pending unreleased entries reconstructed under ## Unreleased.
    • The .changes/block-editor/ directory and any associated unreleased fragments for block-editor were deleted.

Package publishing workflow testing

Note

For the package publishing workflow, this PR opts to use the same system as in trunk for calculating version updates. The only changes in this PR are:

  • How we feed that tool the unreleased changelog (for changie managed changelogs we essentially feed in the output from npm run changelog:preview)
  • How the changelog is subsequently compiled (uses the changie batch/merge commands for changie packages).

For testing this process, it's safest to create a temporary local clone of your gutenberg repo so that the release command cannot push to GitHub.

Prerequisite: Make sure there are unreleased changes in packages, including components and ui.

  1. cd to a folder where you'd like to make the temporary clone (e.g. the parent directory of your Gutenberg repo).
  2. git clone gutenberg temp-gutenberg (where gutenberg is the path to your local working repo).
  3. cd temp-gutenberg
  4. npm install
  5. git remote -v — verify that the remote only points to your local repo.
  6. git checkout -b wp/latest — create a local wp/latest branch.
  7. git push -u origin wp/latest — push the wp/latest branch to your local remote.
  8. npm exec --no release-cli -- npm-bugfix --repository-path . — run the release workflow.
  9. You'll see: 💃 Time to publish WordPress packages to npm 🕺 ... ? Ready to go? (Y/n) — answer yes.
  10. The next prompt will display all recommended package version bumps. Check that they look correct (@wordpress/components bumping major to 44.0.0, @wordpress/ui bumping minor to 0.26.0 due to 0.x rules). It will ask ? All corresponding files were updated. Commit the changes? (Y/n) — answer yes.
  11. The next prompt will ask: ? The release branch is going to be pushed to the remote repository. Continue? (Y/n) — answer no (or press Ctrl+C) to stop before pushing or publishing.
  12. git show — verify the generated commit: .changes/ version files were created, fragments were deleted, and CHANGELOG.md files have the new version merged cleanly under the header.

Tidy up

  1. cd .. to out of the temp-gutenberg repo
  2. rm -rf temp-gutenberg to delete the temp repo
  3. cd gutenberg to go back into your regular gutenberg repo
  4. git branch -D wp/latest to delete the wp/latest branch created earlier (or git reset --hard origin/wp/latest to keep the branch but reset)

Use of AI Tools

OpenCode / Gemini, GPT

@talldan talldan self-assigned this Oct 22, 2026
@talldan talldan added the [Type] Project Management Meta-issues related to project management of Gutenberg label Oct 22, 2026
@github-actions github-actions Bot added [Package] Components /packages/components [Package] UI /packages/ui labels Oct 22, 2026
@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

🤖 PR meta 🤖

Preview in WordPress Playground

📦 Bundle size

Size Change: 0 B

Total Size: 8.66 MB

2fd308c Run

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric 0310dc8 trunk % Change
timeToFirstByte 45.45 ms +6.38% -2.75% 44.8 ms +7.7% -2.68% 1.45%
largestContentfulPaint 74 ms +5.41% -5.41% 72 ms +8.33% -5.56% 2.78%
lcpMinusTtfb 26.2 ms +22.14% -5.92% 25.95 ms +17.53% -6.74% 0.96%
wpBeforeTemplate 23.34 ms +15.94% -1.93% 23.39 ms +15.01% -2.18% -0.21%
wpTemplate 18.02 ms +2.55% -4.66% 17.69 ms +4.52% -3.22% 1.87%
wpTotal 41.91 ms +6.75% -2.67% 41.23 ms +9.1% -2.4% 1.65%
wpMemoryUsage 7.75 MB +0% -0% 7.71 MB +0% -0% 0.45%
wpDbQueries 16 +0% -0% 16 +0% -0% 0%

front-end-classic-theme

Metric 0310dc8 trunk % Change
timeToFirstByte 38.2 ms +6.94% -4.97% 36.8 ms +6.39% -3.94% 3.8%
largestContentfulPaint 68 ms +2.94% -5.88% 68 ms +0% -5.88% 0%
lcpMinusTtfb 28.75 ms +5.74% -3.83% 29.15 ms +4.63% -2.57% -1.37%
wpBeforeTemplate 20.4 ms +12.99% -1.57% 20.21 ms +6.04% -2.52% 0.94%
wpTemplate 14.06 ms +5.33% -4.84% 13.71 ms +2.33% -5.84% 2.55%
wpTotal 35.36 ms +6.5% -5.6% 34 ms +6.26% -3.85% 4%
wpMemoryUsage 6.44 MB +0% -0% 6.40 MB +0% -0% 0.56%
wpDbQueries 13 +0% -0% 13 +0% -0% 0%

media-processing

Metric 0310dc8 trunk % Change
mediaProcessingJpeg 330.34 ms +0.8% -0.99% 327.61 ms +0.86% -0.42% 0.83%
mediaProcessingAvif 4890.66 ms +0.47% -0.11% 4902.97 ms +0.33% -0.42% -0.25%
mediaProcessingJpegToAvif 3411.33 ms +0.23% -0.24% 3407.89 ms +0.25% -0.37% 0.1%

media-upload

Metric 0310dc8 trunk % Change
jpegUploadProcessing 1463.12 ms +1.02% -1.47% 1454.24 ms +0.46% -0.88% 0.61%
pngUploadProcessing 247 ms +4.64% -4.72% 250.25 ms +6.27% -4.13% -1.3%
largeJpegUploadProcessing 1443.3 ms +1.52% -0.3% 1450.59 ms +1.17% -0.36% -0.5%
multipleImageUploadProcessing 1548.56 ms +3.03% -2.22% 1534.57 ms +0.64% -1.94% 0.91%

post-editor

Metric 0310dc8 trunk % Change
serverResponse 258.98 ms +1.88% -1.27% 245.63 ms +3.93% -7.37% 5.44%
firstPaint 280.95 ms +8.33% -6.23% 252.18 ms +15.49% -6.36% 11.41%
domContentLoaded 524.68 ms +2.03% -1.23% 528.32 ms +5.27% -5.34% -0.69%
loaded 525.41 ms +2.03% -1.18% 529.25 ms +5.29% -5.32% -0.73%
firstContentfulPaint 306.63 ms +2.77% -3.96% 301.71 ms +5.1% -3.47% 1.63%
firstBlock 1377.66 ms +1.5% -1.38% 1359.6 ms +3.93% -4.21% 1.33%
type 12.14 ms +6.18% -11.78% 11.36 ms +7.39% -4.05% 6.87%
typeWithoutInspector 12.15 ms +4.69% -7.16% 11.18 ms +5.01% -12.79% 8.68%
typeWithTopToolbar 14.88 ms +7.12% -3.97% 14.71 ms +5.51% -7.48% 1.16%
typeContainer 5.77 ms +10.23% -10.4% 5.06 ms +8.3% -7.91% 14.03%
focus 73.27 ms +7.85% -3.77% 67.16 ms +2.53% -2.5% 9.1%
firstFocus 168.68 ms +0% -0% 152.26 ms +0% -0% 10.78%
selectAll 217.13 ms +11.36% -1.43% 216.14 ms +4.03% -2.8% 0.46%
undo 17.22 ms +6.5% -4.59% 16.91 ms +8.28% -5.68% 1.83%
listViewOpen 44.33 ms +6.2% -5.89% 43.28 ms +3.03% -10.12% 2.43%
inserterOpen 26.19 ms +1.49% -5.04% 24.3 ms +6.5% -7.78% 7.78%
inserterHover 7.23 ms +11.48% -2.77% 7.08 ms +10.59% -2.82% 2.12%
inserterSearch 6.16 ms +1.14% -4.22% 5.57 ms +4.13% -3.23% 10.59%
loadPatterns 405.62 ms +1.9% -1.61% 396.63 ms +5.05% -1.39% 2.27%
wpTotal 252.21 ms +1.89% -1.29% 239.18 ms +3.52% -7.78% 5.45%
wpMemoryUsage 14.81 MB +0% -0% 14.77 MB +0% -0% 0.25%
wpDbQueries 55 +0% -0% 55 +0% -0% 0%

site-editor

Metric 0310dc8 trunk % Change
serverResponse 317.36 ms +1.9% -8.91% 313.66 ms +2.53% -9.2% 1.18%
firstPaint 331.26 ms +6.58% -3.95% 350.28 ms +5.98% -11.62% -5.43%
domContentLoaded 656.63 ms +1% -1.58% 646.8 ms +0.74% -0.23% 1.52%
loaded 657.47 ms +1.02% -1.58% 647.59 ms +0.73% -0.23% 1.53%
firstContentfulPaint 367.22 ms +2.19% -1.62% 368.27 ms +2.41% -1.03% -0.29%
firstBlock 2030.5 ms +0.61% -1.91% 1976.4 ms +0.4% -0.79% 2.74%
type 14.58 ms +2.74% -8.85% 14 ms +9.14% -4.14% 4.14%
navigate 96.03 ms +4.92% -1.3% 96.87 ms +5.2% -6.15% -0.87%
loadPatterns 1062.68 ms +5.43% -10.5% 980.04 ms +4.03% -9.19% 8.43%
loadPages 1007.78 ms +2.14% -2.1% 986.65 ms +2.24% -4.55% 2.14%
wpTotal 309.06 ms +1.95% -9.22% 305.3 ms +2.61% -9.42% 1.23%
wpMemoryUsage 12.82 MB +0% -0% 12.79 MB +0% -0% 0.25%
wpDbQueries 45 +0% -0% 45 +0% -0% 0%

2fd308c Run

🏁 Flaky tests

Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

Undo restores the post selection when another synced entity is loaded (RTC WebSocket) in /test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts, passed after 1 failed attempt.
Error: expect(received).toMatchObject(expected)

- Expected  - 2
+ Received  + 2

  Object {
    "attributeKey": "content",
    "blockIndex": 0,
    "content": "abcdef",
-   "endOffset": 3,
-   "offset": 3,
+   "endOffset": 5,
+   "offset": 5,
  }

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-undo-redo.spec.ts:363:5
does not select blocks in the canvas preview when editing from the sidebar (Site Editor v2) in /test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator: getByRole('combobox', { name: 'Search or type URL' })
Expected: focused
Timeout: 5000ms
Error: element(s) not found

Call log:
  - Expect "toBeFocused" getByRole('combobox', { name: 'Search or type URL' }) with timeout 5000ms
  - waiting for getByRole('combobox', { name: 'Search or type URL' })

    at LinkControl.useLinkControlSearch (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js:416:47)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/site-editor/navigation-sidebar-list-view.spec.js:179:21
should apply a named font size using the font size buttons in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"large"} -->
+ <!-- wp:paragraph {"fontSize":"medium"} -->
- <p class="has-large-font-size">Paragraph to be made "large"</p>
+ <p class="has-medium-font-size">Paragraph to be made "large"</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:153:6
should reset a named font size using input field in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"small"} -->
+ <!-- wp:paragraph {"fontSize":"tiny"} -->
- <p class="has-small-font-size">Paragraph with font size reset using input field</p>
+ <p class="has-tiny-font-size">Paragraph with font size reset using input field</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:216:6
should reset a named font size using the tools panel menu in /test/e2e/specs/editor/various/font-size-picker.spec.js, passed after 1 failed attempt.
Error: expect(received).toBe(expected) // Object.is equality

- Expected  - 2
+ Received  + 2

- <!-- wp:paragraph {"fontSize":"medium"} -->
+ <!-- wp:paragraph {"fontSize":"small"} -->
- <p class="has-medium-font-size">Paragraph with font size reset using tools panel menu</p>
+ <p class="has-small-font-size">Paragraph with font size reset using tools panel menu</p>
  <!-- /wp:paragraph -->

Call Log:
- Timeout 5000ms exceeded while waiting on the predicate
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/font-size-picker.spec.js:178:6
should select synced pattern in /test/e2e/specs/editor/various/writing-flow.spec.js, passed after 1 failed attempt.
Error: expect(locator).toBeFocused() failed

Locator:  locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
Expected: focused
Received: inactive
Timeout:  5000ms

Call log:
  - Expect "toBeFocused" locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]') with timeout 5000ms
  - waiting for locator('[name="editor-canvas"]').contentFrame().locator('[data-type="core/block"]')
    14 × locator resolved to <div tabindex="0" role="document" draggable="true" data-title="Pattern" data-type="core/block" data-is-drop-zone="true" aria-label="Block: Pattern" id="block-c84719d9-761e-4152-9485-e9117c4a81d8" data-block="c84719d9-761e-4152-9485-e9117c4a81d8" class="block-editor-block-list__block wp-block is-selected is-reusable block-library-block__reusable-block-container wp-block-block block-editor-block-list__layout">…</div>
       - unexpected value "inactive"

    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/writing-flow.spec.js:1464:5
three users concurrently edit a large post with diverse blocks in /test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts, passed after 1 failed attempt.
TimeoutError: locator.waitFor: Timeout 17500ms exceeded.
Call log:
  - waiting for getByRole('button', { name: /Collaborators list/ }) to be visible

    at map (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/fixtures/collaboration-utils.ts:193:7)
    at CollaborationUtils.waitForMutualDiscovery (/home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/fixtures/collaboration-utils.ts:188:10)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/collaboration/collaboration-stress.spec.ts:416:28

2fd308c Run

@ciampo ciampo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nice!

I'm thinking of a potential split / rollout:

  1. Add the Changie workspace, configuration format, contributor commands, one shared validator, and fixture-based tests. Keep existing packages on their current workflow.
  2. Add release and CI integration, including the release/backport checks above.
  3. Opt UI in with one historical baseline and its pending fragments. Include the authoring documentation in this change.
  4. Migrate Components after the pilot has completed a package release successfully.

Comment thread .changie.yaml Outdated
# 'auto' specifies the semver increment level.
# Pre-1.0 packages (signaled via GUTENBERG_PRE_1="true"): breaking changes bump minor,
# while stable packages (>=1.0) bump major as usual.
# Note: 'Stable Release' (for promoting 0.x packages to 1.0.0) is handled via

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Could we keep Stable Release in Changie's configured kinds and test promotion through the actual compiler? The command creates a fragment that our validator accepts, but Changie rejects it, which blocks release preparation.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

The command creates a fragment that our validator accepts, but Changie rejects it, which blocks release preparation.

I'll look into that, I thought I tested and it wasn't rejected.

@talldan talldan Oct 28, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yeah, you're right it is rejected. 🤦‍♂️

My initial reason for not doing this is that it makes the prompt look like this:
Screenshot 2026-10-28 at 3 33 48 pm

'Stable Release' shows whenever the user runs the changelog:add command, even when a package is already stable. For it to appear first in the rendered CHANGELOG.md file, it also has to be first in the prompt.

I think I have some workarounds though. We can move the Stable Release kind to last in the list, and add templating to include some additional text underneath the version header whenever a package hits 1.0.0.

We can optionally also omit the changelog entry if that's too duplicative.

There are also other options, like not using a kind to indicate a Stable Release, but instead an optional custom field, and that would mean it isn't part of the prompt at all. For that we'd have to pick another kind like 'Internal'.

edit: implemented the first option to start with, we can iterate.

Comment thread tools/validation/validate-changelogs.ts Resolved
Comment thread tools/changelogs/lib/migrate.ts Resolved
Comment thread tools/release/commands/packages.js Resolved
@aduth

aduth commented Oct 23, 2026 •

Copy link
Copy Markdown
Member

Thanks for exploring this! A few passing comments on the idea of a change in process here:

  • To me, one of the biggest points of friction in managing changelogs is having to come back after the pull request is created to add a link to it, since it can't be known ahead of time. I don't see that this is improved by this proposal. I don't know exactly how we could address this, other than some mechanism where the "final" release notes are generated later, after the pull request is already merged.
  • Developer experience would be a big focus. It's good to see the commands, skills, relevant documentation, and CI feedabck. If this is something we migrate over time, I also anticipate that the fragmented approach would itself become a source of developer friction.

@talldan

talldan commented Oct 26, 2026

Copy link
Copy Markdown
Contributor Author

To me, one of the biggest points of friction in managing changelogs is having to come back after the pull request is created to add a link to it, since it can't be known ahead of time. I don't see that this is improved by this proposal. I don't know exactly how we could address this, other than some mechanism where the "final" release notes are generated later, after the pull request is already merged.

Agree that's another frustration. It also leads to re-starting all the CI jobs just for a changelog entry, so that process is probably making our CI unnecessarily busy.

I see that changie does support adding additional metadata to fragments later - https://changie.dev/config/#postprocessconfig-type (and not up-front in the prompt). We could write a script that looks up the PR number and adds it to existing changelog fragments prior to compiling the changelogs. A benefit is we could consider adding author links too.

Developer experience would be a big focus. It's good to see the commands, skills, relevant documentation, and CI feedabck. If this is something we migrate over time, I also anticipate that the fragmented approach would itself become a source of developer friction.

Yep, agree, though I don't think the migration is particularly challenging, so hopefully it's something that can happen fairly quickly. Though we do have a lot of packages 😄

I'd like to be able to validate that there are no issues first before a broader rollout, so running a trial first would be good. Picking a couple of active packages that have a smaller contributor base would be a good idea. That way the confusion isn't too widespread.

@Mamaduka

Copy link
Copy Markdown
Member

To me, one of the biggest points of friction in managing changelogs is having to come back after the pull request is created to add a link to it

My biggest frustration as well.

How does this work when work spans multiple packages, or when a single branch includes a couple of minor fixes (in the same package) that are required for a general fix?

I've seen AI struggle with those cases and need little hand-holding. AI often assumes all affected areas need a changelog, which we don't always want. For example, in the second scenario, I prefer one general entry with details in the PR.

@talldan
talldan force-pushed the add/changie-for-changelogs branch from c530b4d to 6ebcbeb Compare October 28, 2026 06:39
Comment on lines +249 to +256
if ( cleanFirst && parsed.unreleasedEntries.length === 0 ) {
return {
packageName: normalized,
versionsCreated: 0,
fragmentsCreated: 0,
operations: [],
};
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

After trunk releases all pending entries, this guard skips the update and keeps the old baseline and fragments. The next changie merge removes the new release notes. Could we refresh changed history even when there are no unreleased entries?

Comment on lines +83 to +90
if ( inUnreleased ) {
if ( /^###\s+/.test( line ) ) {
currentKind = line.replace( /^###\s+/, '' ).trim();
i++;
continue;
}

if ( /^-\s+/.test( line ) ) {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The documented manual Stable Release section uses a heading and prose, so this parser drops it during migration. Could we preserve that promotion intent or reject the input before changing files? Otherwise a package intended for 1.0.0 stays on 0.x.

@ciampo

ciampo commented Nov 1, 2026

Copy link
Copy Markdown
Contributor

Apart from the feedback (which I believe still needs to be addressed) from @aduth and @Mamaduka and the one I just left, I think the direction is generally promising.

I'd still suggest splitting the rollout:

  1. Add the tooling, configuration, contributor commands, shared validator, and tests.
  2. Add CI and release integration, including backport guidance.
  3. Pilot the @wordpress/ui package with one historical baseline, pending fragments, and contributor documentation.
  4. Migrate Components after UI has completed a successful package release.

Could that be a good approach?

@ciampo

ciampo commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

(cc @manzoorwanijk - I know you're not really around, but you may want to keep an eye on this for when you're back)

@simison

simison commented Nov 12, 2026

Copy link
Copy Markdown
Member

FYI the script I added in #85386 likely needs updating here after rebase.

@talldan
talldan force-pushed the add/changie-for-changelogs branch from 8db9639 to 2fd308c Compare November 17, 2026 03:03
@talldan

talldan commented Nov 17, 2026

Copy link
Copy Markdown
Contributor Author

Apart from the feedback (which I believe still needs to be addressed) from @aduth and @Mamaduka and the one I just left, I think the direction is generally promising.

I'm in two minds about whether that feedback is something to address straight away, as it adds extra complexity to the initial merge, especially to the publishing stage where there's not always a lot of support when something goes wrong.

Though if we want to test the feasibility I can add something to this PR. We'll consider this PR a proof of concept and derive smaller PRs from it (that was always the approach I wanted to take anyway). We can include it in the rollout plan you described, perhaps after step 4.


I'd still suggest splitting the rollout:

  1. Add the tooling, configuration, contributor commands, shared validator, and tests.
  2. Add CI and release integration, including backport guidance.
  3. Pilot the @wordpress/ui package with one historical baseline, pending fragments, and contributor documentation.
  4. Migrate Components after UI has completed a successful package release.

Could that be a good approach?

Yep, I'm happy with that approach. I think we should hold fire on this until after the current WordPress release is done. It'll reduce the stress for everyone involved!


FYI the script I added in #85386 likely needs updating here after rebase.

Thanks for the heads up, I've rebased this and added some extra code for the peer range checks to handle packages that use changie.

This branch has not been deployed

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

Labels

[Package] Components /packages/components [Package] UI /packages/ui [Type] Project Management Meta-issues related to project management of Gutenberg

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants