Improve the workflow for publishing packages to npm

[gziolo]

It was dicussed on November 13th during weekly WordPress core JavaScript chat. See transcript for more details.

We should join the discussion in RFC: Improving lerna publish issue in Lerna repository and re-share what's included below.

When working on the WordPress 5.0 release cycle we noticed that our workflow for publishing packages to npm isn't ideal. Using Lerna helps a lot but it doesn't solve all issues. We should work towards improving the workflow and address the following items.

✅ Improve the way version bumps are maintained

At the moment we defer to Lerna performing version increments for all packages. We only express our intent for the change inside of the corresponding changelog files when working on PRs. The biggest downside of this approach is that we need to scan all existing changelog files during publishing and re-apply manually the proper version bump for each package. It would be a nice improvement if we could update both changelog and package.json with a new version at the same time when PR gets merged. Lerna could use that and skip the step to ask what version should be applied.

There is also this issue that some packages get updated only because they depend on other updated packages. This is where Lerna is the most helpful because it's almost impossible to detect it manually when you have to maintain 50 packages with independent versioning.

We should investigate whether from-git option would fit in our scenario as it allows to automate version bumps in some ways.

One thing which didn't work well in the past is pushing publish commit. It takes some time to provide all version increments and publish all packages. We had the case where new commit was pushed to master which broke the flow two-fold. We had to rebase the branch before pushing changes which caused that git hash references weren't working properly anymore. Next time we asked Lerna to list which packages have changed, it had to use the previous hash which wasn't ideal.

✅ Help Lerna maintainers to improve publish failures

In the past, we had publishing failures caused by 2FA timeout where we had more packages to publish than it could be handled in 30 seconds. The following steps don't quite work well in the majority of cases:

1. Check if tags were created locally, if yes use git push --tags to send them to upstream (ensure you didn’t create your own tags).
2. Check if publish commit was created, if yes use git push to send it to upstream (ensure your history is in the proper state).
3. Identify all packages that were published and verify there are no local paths for local packages inside package.json files (e.x. "@wordpress/compose": "^1.0.0").
4. cd to each package that needs to be published and run npm publish --otp=******.

It's tons of manual work and we had 2 releases where we published local paths inside package.json files instead of the latest version of dependencies. Example package which was published by accident with the local path instead of npm version:
https://unpkg.com/@wordpress/block-library@2.2.0/package.json

"@wordpress/autop": "file:../autop",
"@wordpress/blob": "file:../blob",
"@wordpress/blocks": "file:../blocks",
"@wordpress/components": "file:../components",
"@wordpress/compose": "file:../compose",
...

There is an open issue where improved 2FA Support is discussed. However, 2FA isn't the only thing that could go wrong in the process so it would be nice to see publish re-tries in the flow and prompts for new OTP token when the current one expires.

☑️ Add on-demand verification for published packages

The last item which I would love to see is a way to verify if published packages are healthy. As mentioned above, we had 2 cases where 2FA timeout caused some issues which led to having broken package.json files on npm. It might happen again, so we should be at least able to detect it immediately and take proper actions.

[gziolo]

There is an open issue where improved 2FA Support is discussed. However, 2FA isn't the only thing that could go wrong in the process so it would be nice to see publish re-tries in the flow and prompts for new OTP token when the current one expires.

OTP prompts are now implemented in Lerna and we have already upgraded the version we use. This part can be considered done.

[ntwb]

It's tons of manual work and we had 2 releases where we published local paths inside package.json files instead of the latest version of dependencies. Example package which was published by accident with the local path instead of npm version:
https://unpkg.com/@wordpress/block-library@2.2.0/package.json

"@wordpress/autop": "file:../autop",
"@wordpress/blob": "file:../blob",
"@wordpress/blocks": "file:../blocks",
"@wordpress/components": "file:../components",
"@wordpress/compose": "file:../compose",
...

There is a rule that could help us in this regard:

https://npmpackagejsonlint.org/docs/en/rules/dependencies/no-file-dependencies

I'm not sure how we could implement this rule with Lerna though to be honest, as the files in the repo (even tagged releases) still require file:../* references, it is only the published files we want to ensure this is not the case. 🤔

[ntwb]

Observations whilst looking to publish package updates to npm:

Background: This PR has not been published to npm and is causing issues due to semantic versioning of packages included in the @wordpress/scripts package.

Being able to publish updates to npm in this situations where a package that is becoming highly depended upon should be something that we should be able to do without having to wait for a WordPress major/minor release.

Note: I believe this is currently possibly, just undocumented.

---

My best guess based on the Packages Releases and WordPress Core Updates docs was to cherry pick the commit referenced from the above PR into the release/7.1 and to create a PR to merge into the wp/trunk branch and publish to npm from the wp/trunk branch.

That's where I got to and have not gone any further.

[gziolo]

My best guess based on the Packages Releases and WordPress Core Updates docs was to cherry pick the commit referenced from the above PR into the release/7.1 and to create a PR to merge into the wp/trunk branch and publish to npm from the wp/trunk branch.

That's where I got to and have not gone any further.

I'm sure, it's enough to cherry pick this individual commit directly into wp/trunk and publish patch release for the package. We should add a section in docs to be able to cover such a scenario moving forward.

[ntwb]

I'm sure, it's enough to cherry pick this individual commit directly into wp/trunk and publish patch release for the package. We should add a section in docs to be able to cover such a scenario moving forward.

Thanks, will give this a go now done...

I've created a pull request in #19381 to document the procedure.

[gziolo]

#19764 automates version bumps by updating CHANGELOG files with the recommended version and publish date.

[gziolo]

I think the workflow is in good shape. We still test published packages manually. However, we now have packages-update script in @wordpress/script package that makes it easier to update npm packages. We also regularly update those packages in WordPress core and gutenberg-examples repositories so it’s very unlikely that we ship something completely broken.