Repository navigation
Conversation
🤖 PR meta 🤖📦 Bundle sizeSize Change: 0 B Total Size: 8.66 MB
⚡ PerformanceShow the resultsClient side metrics exclude the server response time. front-end-block-theme
front-end-classic-theme
media-processing
media-upload
post-editor
site-editor
🏁 Flaky testsSome 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
|
ciampo
left a comment
There was a problem hiding this comment.
Nice!
I'm thinking of a potential split / rollout:
- Add the Changie workspace, configuration format, contributor commands, one shared validator, and fixture-based tests. Keep existing packages on their current workflow.
- Add release and CI integration, including the release/backport checks above.
- Opt UI in with one historical baseline and its pending fragments. Include the authoring documentation in this change.
- Migrate Components after the pilot has completed a package release successfully.
| # '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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Yeah, you're right it is rejected. 🤦♂️
My initial reason for not doing this is that it makes the prompt look like this:

'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.
|
Thanks for exploring this! A few passing comments on the idea of a change in process here:
|
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.
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. |
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. |
c530b4d to
6ebcbeb
Compare
| if ( cleanFirst && parsed.unreleasedEntries.length === 0 ) { | ||
| return { | ||
| packageName: normalized, | ||
| versionsCreated: 0, | ||
| fragmentsCreated: 0, | ||
| operations: [], | ||
| }; | ||
| } |
There was a problem hiding this comment.
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?
| if ( inUnreleased ) { | ||
| if ( /^###\s+/.test( line ) ) { | ||
| currentKind = line.replace( /^###\s+/, '' ).trim(); | ||
| i++; | ||
| continue; | ||
| } | ||
|
|
||
| if ( /^-\s+/.test( line ) ) { |
There was a problem hiding this comment.
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.
|
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:
Could that be a good approach? |
|
(cc @manzoorwanijk - I know you're not really around, but you may want to keep an eye on this for when you're back) |
|
FYI the script I added in #85386 likely needs updating here after rebase. |
…nts and @wordpress/ui
…elog:promote-stable script
…tion and update guide
…e and batch versions
…tool and update packages
…s-yaml dependency
…ation to single baseline
8db9639 to
2fd308c
Compare
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.
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!
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. |
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)
Testing Instructions
Add a changelog entry
npm run changelog:add.git status/git diff— observe that an independent.yamlfragment was created under.changes/unreleased/.Preview unreleased changes for a package
npm run changelog:preview -- componentsornpm run changelog:preview -- uito 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
npm run changelog:promote-stable -- ui.Stable Releasewas created.npm run changelog:promote-stable -- componentsand verify that it rejects the promotion because@wordpress/componentsis 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:addcommand.Migrate a package to changie
git checkout -b update/block-editor-changelogs-to-changie.npm run changelog:migrate -- block-editor --dry-runto inspect version counts.npm run changelog:migrate -- block-editor.git status— observe that.yamlfragments were created for all unreleased entries, past versions were split into.changes/block-editor/*.md, andpackages/block-editor/CHANGELOG.mdhad its "Unreleased" section removed.Updating an in-progress migration
If a migration branch falls behind
trunkthere's a chance new old-style changelog entries were added ontrunk. The migration will need to be updated:git pull --rebase origin trunk.CHANGELOG.md, keep trunk's version:git checkout origin/trunk -- packages/block-editor/CHANGELOG.mdnpm run changelog:migrate -- block-editor --update.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.mdmaintenance:npm run changelog:migrate -- block-editor --rollbackgit status— observe that:packages/block-editor/CHANGELOG.mdwas restored with its full version history and any pending unreleased entries reconstructed under## Unreleased..changes/block-editor/directory and any associated unreleased fragments forblock-editorwere deleted.Package publishing workflow testing
Note
For the package publishing workflow, this PR opts to use the same system as in
trunkfor calculating version updates. The only changes in this PR are:changiemanaged changelogs we essentially feed in the output fromnpm run changelog:preview)changiebatch/mergecommands 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
componentsandui.cdto a folder where you'd like to make the temporary clone (e.g. the parent directory of your Gutenberg repo).git clone gutenberg temp-gutenberg(wheregutenbergis the path to your local working repo).cd temp-gutenbergnpm installgit remote -v— verify that the remote only points to your local repo.git checkout -b wp/latest— create a localwp/latestbranch.git push -u origin wp/latest— push thewp/latestbranch to your local remote.npm exec --no release-cli -- npm-bugfix --repository-path .— run the release workflow.💃 Time to publish WordPress packages to npm 🕺 ... ? Ready to go? (Y/n)— answer yes.@wordpress/componentsbumping major to 44.0.0,@wordpress/uibumping 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.? 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.git show— verify the generated commit:.changes/version files were created, fragments were deleted, andCHANGELOG.mdfiles have the new version merged cleanly under the header.Tidy up
cd ..to out of thetemp-gutenbergreporm -rf temp-gutenbergto delete the temp repocd gutenbergto go back into your regular gutenberg repogit branch -D wp/latestto delete thewp/latestbranch created earlier (orgit reset --hard origin/wp/latestto keep the branch but reset)Use of AI Tools
OpenCode / Gemini, GPT