Packages: Automate npm publishing as part of Gutenberg release workflow #39259
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Size Change: +18 B (0%) Total Size: 1.16 MB
ℹ️ View Unchanged
|
gziolo
force-pushed
the
update/npm-publishing-workflow-changes
branch
from
f5c476f to
13a29c0
Compare
gziolo
force-pushed
the
update/npm-publishing-workflow-changes
branch
6 times, most recently
from
cb0b699 to
c5e79fc
Compare
gziolo
force-pushed
the
update/npm-publishing-workflow-changes
branch
from
9ae910d to
d7c77dc
Compare
gziolo
requested review from
ntwb,
nerrad,
ajitbohra,
mkaz and
ryanwelcher
as code owners
gziolo
added
[Type] Project Management
gziolo
changed the title
|
I love this idea! I'm not familiar enough with the code here to be comfortable approving it but this has my upvote for sure :) |
youknowriad
approved these changes
Mar 9, 2022
|
I update the documentation to emphasize why we publish packages to npm at the time of Gutenberg RC1 release. It's important to have it documented as it might be tempting to move that moment by one week as we used to have it in the past. I also included a note why we will start a In the next two weeks, I plan to summarize the current status and propose the next steps as an official post at https://make.wordpress.org/core/. |
There was a problem hiding this comment.
Automating the release process further is always a good thing 🎉
I left some questions below about how this is going to work with the WP release process. I assume we'll be using patch releases exclusively to backport changes after WP code freeze?
It would be great to explain clearly what the process will be in the docs (or at least our current assumptions about the process, things can always change later of course 😄 )
| @@ -192,35 +192,31 @@ The Gutenberg repository mirrors the [WordPress SVN repository](https://make.wor | |||
|
|
|||
| - The `wp/trunk` branch contains the same version of packages published to npm with the `latest` distribution tag. The WordPress core consumes those packages directly in the `trunk` branch and uses them for public releases. | |||
| - The `wp/next` branch contains the same version of packages published to npm with the `next` distribution tag. Projects should use those packages for development purposes only. | |||
| - A Gutenberg branch targeting a specific WordPress major release (including its further minor increments) is created (example `wp/5.2`) based on the `wp/trunk` Gutenberg branch when the corresponding WordPress release branch is created. (This usually happens when the first `RC` of the next WordPress major version is released). | |||
| - A Gutenberg branch targeting a specific WordPress major release (including its further minor increments) is created (example `wp/5.2`) based on the `wp/trunk` Gutenberg branch when the corresponding WordPress release branch is created. (This usually happens when the `beta` or `RC` of the next WordPress major version is released). | |||
There was a problem hiding this comment.
Does this mean the WP release branch will be created at Beta going forward, or are we planning to create the Gutenberg release branch before the WP one?
There was a problem hiding this comment.
I think it is strictly RC in WordPress core. I see it's scheduled for WP 6.0 at the time the first RC happens. In practice, it means we will have to cut a new wp/6.0 branch at the time when cherry-pick first commits from the Gutenberg plugin release that doesn't get included in the WordPress release. So that means a bit earlier.
I don't think it doesn't change much in the process, because previously we would use wp/trunk for publishing dedicated for WordPress core, and here we just use a different branch wp/6.0.
There was a problem hiding this comment.
Yeah, that makes sense. I think in WP too it would be better to create the release branch straight after Beta, but that might not change anytime soon, and nothing stops us from creating the Gutenberg release branch earlier.
To make the docs clear, perhaps we can specify that the Gutenberg release branch is created as soon as code freeze (or Beta 1, if there's no prior code freeze) happens in Core.
|
|
||
| Note that the WordPress `trunk` branch can be closed or in "feature-freeze" mode. Usually, feature freeze in WordPress Core happens about 2 weeks before Beta 1 and remains in effect until RC1 when the `trunk` gets branched. During this period, the Gutenberg plugin releases should not be synchronized with WordPress Core. | ||
| We deliberately update the `wp/trunk` branch within the Gutenberg repo with the content from the Gutenberg release `release/*` (example `release/12.7`) branch at the time of the Gutenberg RC1 release. This is done to ensure that the `wp/trunk` branch is as close as possible to the latest version of the Gutenberg plugin. It also practically removes the chances of conflicts while backporting to `trunk` commits with updates applied during publishing to `package.json` and `CHANGELOG.md` files. In the past, we had many issues in that aspect when doing npm publishing after the regular Gutenberg release a week later. When publishing the new package versions to npm, we pick at least the `minor` version bump to account for future bugfix or security releases. |
There was a problem hiding this comment.
Do we update Core trunk after each Gutenberg release too? If not, does it really make sense to keep calling this branch wp/trunk if it's not in sync with Core trunk?
There was a problem hiding this comment.
Great question. In the past, we used that branch several times to update the trunk in the WordPress core with changes published from wp/trunk before the beta for the major WordPress release. Nothing stops us from doing it on regular basis 😅
There are only 3 weeks between beta 1 (12 April) and RC 1 (3 May) for WP 6.0 so it's a relatively short period of time where wp/6.0 would exist in Gutenberg without 6.0 branch in WP core. Anyway, we can just rename it to wp/latest to better express its intent.
There was a problem hiding this comment.
Nothing stops us from doing it on regular basis 😅
Totally agree we should do this! I think the only thing that stops us is not wanting to throw all the super experimental/unstable stuff into Core, but we can maybe make more use of feature flags.
we can just rename it to wp/latest
That would be be ideal if it's not always going to match WP trunk 🙂
Yes, that was my initial idea to use The alternative is to use more granular dist-tags on npm that are tied to the WordPress major release line. Let me give an example:
The benefit of that strategy would be that you could simplify updating packages in WordPress core because you could run for example: npm install @wordpress/[email protected]That would update
Yes, that's the tricky part because we need to test everything in action. I'm definitely willing to spend more time polishing this flows and distilling the most important parts in the release documentation. |
11 tasks
gziolo
commented
Mar 11, 2022
| npm-publish: | ||
| name: Publish WordPress packages to npm | ||
| runs-on: ubuntu-latest | ||
| needs: update-changelog |
There was a problem hiding this comment.
Let's put npm access token into its own enviroment:
environment: npm organization
|
I was thinking about the changes to the publishing process based on the feedback from @tellthemachines and this is my current thinking posted in the higher-level discussion for better visibility: #37820 (comment). |
|
#39389 covers all the improvements discussed after this PR got merged. Thank you again for your great feedback. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What
Related PR with manually triggered npm publishing: #37751.
Related discussion: #37820.
I'm proposing a new strategy where the "feature-freeze" mode in WordPress Core isn't taken into account when publishing npm packages with the
latesttag. The plan is to publish to npm every time the Gutenberg plugin RC1 is released.Every plugin release (RC1) will trigger at least a
minorversion bump for packages with production code. I also want to automate adding a CHANGELOG entry that links to the GitHub release page with the full plugin release changelog.As long as those changes are applied as a
patchversion bump then it should be good for the time being. An alternative to consider as a follow-up would be to enforce amajorversion bump to production packages on the plugin release that won't be included in the upcoming major WordPress release. The latter is more difficult to handle but I think @ockham had some ideas on how to detect this exact moment.The only non-blocking remaining question is whether we would use
patchdist-tag for beta and RC phase of major WordPress releases or we switch to tags targeting a given release line as discussed in #37820 (reply in thread). In the case of the upcoming WordPress 6.0 release, we could start usingwp-6.0tag instead. This proposal is tracked in #24376.In the long run, we could simplify npm publishing for minor WordPress releases (like 5.9.x) so you could trigger it from the GitHub UI using similar automation that we have for plugin releases. For the time being, the changes proposed in this PR don't impact this type of releases at all.
Why
We have GitHub automation in place for handling the Gutenberg plugin releases.
Prior work:
We should bring the same experience when publishing WordPress packages to npm to make the whole process predictable and more transparent.
npm publishing is still a manual process that has its quirks when the WordPress trunk branch can be closed or in "feature-freeze" mode as documented in Synchronizing WordPress Trunk. There is also a limited group of folks who have access to WordPress organization on npm. It's a lot of overhead to add new contributors there and train them.
How
npm access token
I created a new npm user gutenbergplugin that mirrors the @gutenbergplugin user that handles the Gutenberg plugin releases on GitHub.
I followed the instructions from npm documentation to create an access token for npm publishing:
https://docs.npmjs.com/creating-and-viewing-access-tokens
I followed the instructions from the following article on how to configure a GitHub action to perform npm publishing with the token:
https://dev.to/astagi/publish-to-npm-using-github-actions-23fn
As part of that, I went to "Settings" -> "Secrets". I clicked on "New repository secret" and added the npm access token that I previously copied from npm. It's available in GitHub actions as
secrets.NPM_TOKENwhenever you want to use gutenbergplugin for automated npm interactions.This way npm publishing triggered from GitHub actions will always use a bot user instead of private accounts. It removes all the friction of managing the WordPress organization on npm 🎉
GitHub workflow
I added a new job in the workflow that handles Gutenberg plugin releases. It is going to be triggered:
The job for the first test run will publish WordPress packages to npm based on the plugin release with the
nextdist-tag. That means we won't update the production version of npm packages but those distributed for development purposes. This is intentional to minimize the risk that something goes wrong.Testing instructions
I don't think there is a simple way to test those changes without triggering a real Gutenberg plugin RC1 release.
I tested it in a very hacky way by injecting the job into the Static Analysis workflow that gets triggered on every commit to the PR. You can check the last testing version in f74fdf3. I was able to successfully publish all WordPress npm packages to npm with the
nextdist tag:All the following changes to the
wp/nextbranch got applied from testing runs triggered from this branch:It took me some time to sort out npm access permissions when interacting with Lerna. The commit related to the successful publishing is c510818.