Update the npm packages release process #14136
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -186,25 +186,55 @@ If you don't have access to [make.wordpress.org/core](https://make.wordpress.org | |
|
|
||
| ## Packages Releases and WordPress Core Updates | ||
|
|
||
| The Gutenberg repository mirrors the [WordPress SVN repository](https://make.wordpress.org/core/handbook/about/release-cycle/) in terms of branching for each SVN branch, a corresponding Gutenberg `wp/*` branch is created: | ||
|
|
||
| - The `wp/trunk` branch contains all the packages that are published and used in the `trunk` branch of WordPress. | ||
| - A Gutenberg branch targetting a specific WordPress release and its minors is created (example `wp/5.2`) based on the `wp/trunk` Gutenberg branch when the WordPress `trunk` branch is marked as "feature-freezed". (This usually happens when the first `beta` of the next WordPress major version is released). | ||
youknowriad marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### Synchronizing WordPress Trunk | ||
|
|
||
| For each Gutenberg plugin release, WordPress trunk should be synchronized with this release. This involves the following steps: | ||
|
|
||
| **Note:** The WordPress `trunk` branch can be closed or in "feature-freeze" mode. Usually, this happens between the first `beta` and the first `RC` of the WordPress release cycle. During this period, the Gutenberg plugin releases should not be synchronized with WordPress Core. | ||
|
There was a problem hiding this comment. Should this note be moved after the list? There was a problem hiding this comment. I prefer to keep it here, as it's important to read and stop the process if |
||
|
|
||
| 1. Ensure the WordPress `trunk` branch is open for enhancements. | ||
| 2. Check out the last published Gutenberg release branch `git checkout release/x.x` | ||
| 3. Create a Pull Request from this branch targetting `wp/trunk`. | ||
| 4. Merge the Pull Request. | ||
|
|
||
| Now, the branch is ready to be used to publish the npm packages. | ||
|
|
||
| 1. Check out the `wp/trunk` branch. | ||
| 2. Run the [package release process] but when asked for the version numbers to choose for each package, (assuming the package versions are written using this format `major.minor.patch`) make sure to bump at least the `minor` version number. For example, if the CHANGELOG of the package to be released indicates that the next unreleased version is `5.6.1`, choose `5.7.0` as a version. | ||
|
There was a problem hiding this comment. I see this as troublesome, not all packages get published during the package release process and I'm not sure what the point of bumping the minor version in Also, as we're hoping for wider spread usage from both inside and outside of the WordPress ecosystem bumping the minor version for no apparent reason is not very semantic version friendly. There was a problem hiding this comment. The idea is that there will be potential bug fixes and security fixes we're not aware and we'll leave room for it. In general a Gutenberg release means enhancements... and not everything is mentioned in the CHANGELOG. With our lerna process, packages will be meant to be published without even touching them, if we change one of their dependencies. There was a problem hiding this comment. We're struggling because of this at the moment, we can't update trunk because there might be a 5.1.1 for WordPress requiring security fixes or bug fixes we're not aware of. Right now we default to patch when we don't know and it's blocking us. I think this is the biggest improvement in this proposal There was a problem hiding this comment. Right, but shouldn't the team be made aware of pending security issues to accommodate this? At this moment, if we were to publish an update to a package, and we bumped the minor version there is no way of knowing that another security issue will be raised in the following days to which once again the package will have to have the minor bumped again and republished. Will think on this some more overnight... 🤔 |
||
| 3. Update the `CHANGELOG.md` files of the published packages with the new released versions and commit to the `wp/trunk` branch. | ||
| 4. Cherry-pick the "Publish" (created by Lerna) and the CHANGELOG update commits into the `master` branch of Gutenberg. | ||
|
|
||
| Now, the npm packages should be ready and a patch can be created and commited into WordPress `trunk`. | ||
|
There was a problem hiding this comment. I think creating this kind of patches for WordPress deserves its own section/doc. |
||
|
|
||
|
|
||
| ### Minor WordPress Releases | ||
|
|
||
| The following workflow is needed when bug fixes or security releases need to be backported into WordPress Core. This can happen in a few use-cases: | ||
|
There was a problem hiding this comment. FYI: To be aware of, WordPress currently backports when possible all the way back to WP 3.7 This raises the possibility that Gutenberg may also require patching back to For example, if a security issue is discovered later today and is proposed to be fixed in There was a problem hiding this comment. That's exactly why we need to leave "room" for bug fixes and security fixes in the package version number. There was a problem hiding this comment. Package version numbers cannot work like that as semantic versioning dictates that once There was a problem hiding this comment.
What makes you say that? How do npm package maintainers publish security fixes for old major and minor versions without forcing people to upgrade? There was a problem hiding this comment. They don't, people are forced to upgrade to the version with the security fix. For example, if a vulnerability is discovered in version There was a problem hiding this comment. I think you're wrong, here's an example https://reactjs.org/blog/2018/08/01/react-v-16-4-2.html There was a problem hiding this comment. This is where trying to align semantic versioning of packages with the WP release versioning clashes. The problem here is that a latest release of a package could result in new features to the WP version the security fix is for. This could be mitigated some by the use of the new feature flags functionality in GB but does complicate things. There was a problem hiding this comment.
I just read through the semver specs and I'm not seeing this as something that is codified. Is this something that is documented as a rule somewhere? There was a problem hiding this comment.
I don't think the spec has an opinion on this, but I've never read it that way. If so, something like PHP isn't following semver. Maintaining LTS for a specific minor release wouldn't be possible. I always interpreted the spec as any individual version is just a comparison of the versions that are lower than it, regardless of release date. There was a problem hiding this comment. @nerrad @earnjam I was not inferring a SemVer spec, I was inferring it as a restriction of the npm platform, that said: @youknowriad I. Did. Not. Know. That. 💥 (I've just confirmed with npm that this can be done, also advised not to publish the backported releases with the That will make things far simpler, though thinking about the "room" that we would leave behind, if version |
||
|
|
||
| - During the `beta` and the `RC` period of the WordPress release cycle. | ||
| - For WordPress minor releases and WordPress security releases (example `5.1.1`). | ||
|
|
||
|
There was a problem hiding this comment. Should There was a problem hiding this comment. Maybe it can be reworded, but the reason it's here is to ensure that people are aware when to apply this flow before really applying it. |
||
| 1. Cherry-pick | ||
| 2. Check out the last published Gutenberg release branch `git checkout release/x.x` | ||
| 3. Create a Pull Request from this branch targetting the WordPress related major branch (Example `wp/5.2`). | ||
| 4. Merge the Pull Request. | ||
|
|
||
| Now, the branch is ready to be used to publish the npm packages. | ||
|
|
||
| 1. Check out the WordPress branch used before (Example `wp/5.2`). | ||
| 2. Run the [package release process] but when asked for the version numbers to choose for each package, (assuming the package versions are written using this format `major.minor.patch`) make sure to bump only the `patch` version number. For example, if the last published package version for this WordPress branch was `5.6.0`, choose `5.6.1` as a version. | ||
|
|
||
| **Note:** For WordPress `5.0` and WordPress `5.1`, a different release process was used. This means that when choosing npm package versions targetting these two releases, you won't be able to use the next `patch` version number as it may have been already used. You should use the "metadata" modifier for these. For example, if the last published package version for this WordPress branch was `5.6.1`, choose `5.6.1+patch.1` as a version. | ||
|
There was a problem hiding this comment. This will be problematic for other projects using our packages, it is not semver friendly at all. See also my above comment https://github.com/WordPress/gutenberg/pull/14136/files#r260688733 There was a problem hiding this comment. What alternatives do we have? There was a problem hiding this comment. Continue to use semantic versioning: If WordPress That version There was a problem hiding this comment. The thing is There was a problem hiding this comment. For the past you cannot, the deprecations in the packages will have to support the previous versions of WordPress per the Gutenberg deprecation policy There was a problem hiding this comment. I'm not talking about breaking any compatibility here. I'm taking about:
(These are random numbers to illustrate) A security issue is discovered and concerns all these packages, WordPress has to ship a security release for both Contraints:
Which versions do you publish and include in the WordPress releases There was a problem hiding this comment. Based on the above #14136 (comment) knowing that we can backport the fixes going for the option of bumping the packages minor version number before release would allow us to avoid the above scenario... As the WP 5.0 branch would have v9.0.x of the package, before releasing WP 5.1 the package minor is bumped to v9.1.x, this allows for multiple 9.0.x release to be backport puiblished for WP 5.0.x's, eg, For projects other than WordPress using our packages, a note on all the repos that a minor bump to all packages occurs when WP publishes a new version should document for the most part as to why we are slightly breaking semver on our packages, occasionly. There was a problem hiding this comment.
In my example, this is not possible because There was a problem hiding this comment. Yes, I realise that, what I'm saying is we should do as you suggested above, and in the above scenario before WP 5.1 was shipped we would have bumped the editor package from the current |
||
|
|
||
| 3. Update the `CHANGELOG.md` files of the published packages with the new released versions and commit to the corresponding branch (Example `wp/5.2`). | ||
| 4. Cherry-pick the CHANGELOG update commits into the `master` branch of Gutenberg. | ||
|
|
||
| Now, the npm packages should be ready and a patch can be created and commited into the corresponding WordPress SVN branch. | ||
|
|
||
| --------- | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Currently the https://github.com/wordpress/wordpress-develop repo uses
x.yfor branches, andx.y.zfor tags, this includes the major releases tagged asx.y.z, for example5.1.0• https://github.com/WordPress/wordpress-develop/branches
• https://github.com/WordPress/wordpress-develop/tags
I suggest rather than
wp/5.2thatwp/5.2.0is used so that Gutenberg uses a consistent 3 digit nomenclature?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think Gutenberg should use the same thing
wp/5.2for the branch andx.y.zfor tags. thewp/5.2will serve for all5.2.1,5.2.2...There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When WordPress releases a major release it is both branched and tagged, so a
5.0branch is created, and a5.1.0tag is created:•
5.0branch https://github.com/WordPress/wordpress-develop/tree/5.1•
5.1.0tag https://github.com/WordPress/wordpress-develop/tree/5.1.0All
package.jsonfiles use the 3 digit nomenclature:https://github.com/WordPress/wordpress-develop/blob/5.1.0/package.json#L3:
Also, to note that the
5.0branch has now had 4 minor releases so the 5.0 branchpackage.jsonfile is now5.0.4:https://github.com/WordPress/wordpress-develop/blob/5.0/package.json#L3:
If as you suggest, Gutenberg only use
wp/5.2for all5.2.xreleases I think that would work and be less work to maintain....There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Tags are automatically created by Lerna when we publish the packages. we can probably also tag
wp-5.2.1ourselves, but the issue is that at the time of the npm release, we don't know yet if it's the final npm release that will be merged in this WP version and if we won't need more. So maybe just using the branch and the lerna tags is enough.