Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.
Sign upUpdate the npm packages release process #14136
Conversation
youknowriad
added
the
[Type] Documentation
label
Feb 27, 2019
youknowriad
self-assigned this
Feb 27, 2019
youknowriad
requested review from
ajitbohra,
chrisvanpatten,
gziolo,
mkaz,
nosolosw and
notnownikki
as
code owners
Feb 27, 2019
youknowriad
requested review from
aduth,
ntwb and
mcsf
Feb 27, 2019
youknowriad
reviewed
Feb 27, 2019
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`. |
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
I think creating this kind of patches for WordPress deserves its own section/doc.
ntwb
reviewed
Feb 27, 2019
|
||
### Major WordPress Releases | ||
- 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). |
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
Member
Currently the https://github.com/wordpress/wordpress-develop repo uses x.y
for branches, and x.y.z
for tags, this includes the major releases tagged as x.y.z
, for example 5.1.0
• https://github.com/WordPress/wordpress-develop/branches
• https://github.com/WordPress/wordpress-develop/tags
I suggest rather than wp/5.2
that wp/5.2.0
is used so that Gutenberg uses a consistent 3 digit nomenclature?
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
I think Gutenberg should use the same thing wp/5.2
for the branch and x.y.z
for tags. the wp/5.2
will serve for all 5.2.1
, 5.2.2
...
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
Member
When WordPress releases a major release it is both branched and tagged, so a 5.0
branch is created, and a 5.1.0
tag is created:
• 5.0
branch https://github.com/WordPress/wordpress-develop/tree/5.1
• 5.1.0
tag https://github.com/WordPress/wordpress-develop/tree/5.1.0
All package.json
files use the 3 digit nomenclature:
https://github.com/WordPress/wordpress-develop/blob/5.1.0/package.json#L3:
"version": "5.1.0",
Also, to note that the 5.0
branch has now had 4 minor releases so the 5.0 branch package.json
file is now 5.0.4
:
https://github.com/WordPress/wordpress-develop/blob/5.0/package.json#L3:
"version": "5.1.0",
If as you suggest, Gutenberg only use wp/5.2
for all 5.2.x
releases I think that would work and be less work to maintain....
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
Tags are automatically created by Lerna when we publish the packages. we can probably also tag wp-5.2.1
ourselves, 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.
ntwb
reviewed
Feb 27, 2019
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. |
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
Member
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 major.minor.patch
achieves here.
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.
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
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.
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
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
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
Member
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...
ntwb
reviewed
Feb 27, 2019
|
||
### Minor WordPress Releases | ||
|
||
For minor releases, the critical fixes targeted for this WordPress Minor release should be cherry-picked into the `g-minor` branch one by one in their chronological order. | ||
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: |
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
Member
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 5.0
For example, if a security issue is discovered later today and is proposed to be fixed in 5.1.1
it is conceivably possible that the packages be updated will have to be backported to WordPress versions 5.0
and 5.1
as such the Gutenberg branches wp/5.0
, wp/5.1
, and wp/trunk
will all require updating at this time.
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
That's exactly why we need to leave "room" for bug fixes and security fixes in the package version number.
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
Member
Package version numbers cannot work like that as semantic versioning dictates that once 6.7.0
is published, 6.6.9
cannot be published, nothing less than 6.7.0
can be published.
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
semantic versioning dictates that once
6.7.0
is published,6.6.9
cannot be published,
What makes you say that? How do npm package maintainers publish security fixes for old major and minor versions without forcing people to upgrade?
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
•
Member
They don't, people are forced to upgrade to the version with the security fix.
For example, if a vulnerability is discovered in version 1.1.1
of a package, and that same package is now at version 7.8.9
, the fix for the 1.1.1
vulnerability must be released in either 7.8.10
, 7.9.0
, or 8.0.0
. A 1.1.2
or 1.2.0
cannot be published.
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
I think you're wrong, here's an example https://reactjs.org/blog/2018/08/01/react-v-16-4-2.html
This comment has been minimized.
This comment has been minimized.
nerrad
Feb 27, 2019
Contributor
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.
This comment has been minimized.
This comment has been minimized.
nerrad
Feb 27, 2019
Contributor
Package version numbers cannot work like that as semantic versioning dictates that once
6.7.0
is published,6.6.9
cannot be published, nothing less than6.7.0
can be published.
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?
This comment has been minimized.
This comment has been minimized.
earnjam
Feb 27, 2019
Contributor
Package version numbers cannot work like that as semantic versioning dictates that once
6.7.0
is published,6.6.9
cannot be published, nothing less than6.7.0
can be published.
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.
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 28, 2019
•
Member
@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 latest
npm tag.)
That will make things far simpler, though thinking about the "room" that we would leave behind, if version 1.1.1
of a package is already published, we bump the minor so that it becomes version 1.2.0
, if we then have to patch version 1.1.1
for a vulnerability, by publishing the fix in 1.1.2
is that ok for semantic versioning? There is the possibility the "fix" breaks _backward compatibility which means the package should have been bumped by the minor version and not the patch version
ntwb
reviewed
Feb 27, 2019
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. |
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
Member
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
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
•
Member
Continue to use semantic versioning:
If WordPress 5.1.1
is planned due to a security issue with the @wordpress/editor
package which is at the time of writing is currently version 9.0.11
then the @wordpress/editor
package is patched, updated, and published as version 9.1.0
.
That version 9.1.0
version of @wordpress/editor
is then backported into both the wp/5.0
and wp/5.1
branches (and wp/trunk
)
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
The thing is 9.1.0
might already exist because the wp.5.2
might have already included it, so how do you go about patching the old versions without also adding features from the new versions?
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 27, 2019
Member
For the past you cannot, the deprecations in the packages will have to support the previous versions of WordPress per the Gutenberg deprecation policy
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 27, 2019
Author
Contributor
I'm not talking about breaking any compatibility here. I'm taking about:
WP 5.0.3
includes the editor package with9.0.11
WP 5.1
includes the editor package with version9.0.12
Trunk
includes the editor package with version9.1.0
(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 5.0
, 5.1
and also fix the issue in trunk. How do we proceed?
Contraints:
- We want to include only this security fix for the previous versions, we don't want to add features that have been built for future versions.
Which versions do you publish and include in the WordPress releases 5.0.4
, 5.1.1
and trunk?
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 28, 2019
Member
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, 9.0.11
for WP 5.0.3
, 9.0.12
for WP 5.0.4
, 9.0.13
for WP 5.0.5
etc etc, and for WP 5.1.x, 9.1.1
, 9.1.2
, 9.1.3
and on are available, bump the minor again for WP 5.2 and 9.2.x
range is available.
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.
This comment has been minimized.
This comment has been minimized.
youknowriad
Feb 28, 2019
Author
Contributor
9.0.12
for WP5.0.4
In my example, this is not possible because 9.0.12
already existed and is used in 5.1
and we don't have room to add fixes between 9.0.11
and 9.0.12
, that's why this is a special case using "metadata". I know that it's not perfect and that it's not "full semver" as npm will consider these versions as the same unless you explicitely target one but I don't think we have choices here because this scenario already happened, in this part, I'm trying to find a way to solve it when we face it.
This comment has been minimized.
This comment has been minimized.
ntwb
Feb 28, 2019
Member
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 9.0.11
to 9.1.0
, thus WP 5.1 would have shipped with 9.1.0
and we'd have the remaining 9.0.x
versions for as many WP 5.0.x releases required over the coming years, WP 5.0.55 would use 9.0.66
nosolosw
reviewed
Feb 27, 2019
docs/contributors/release.md Outdated
This comment has been minimized.
This comment has been minimized.
Let's move forward here to unblock npm package releases, can I get a |
gziolo
approved these changes
Mar 4, 2019
I had some minor notes only. In general, it seems to be solid and it aligns perfectly fine with what I have been thinking lately about this process. I was very disappointed that we couldn't publish the latest changes to npm since the very early January. All the changes proposed will make it all much more flexible and should allow us to do releases at will unless WordPress trunk is frozen. If that is still an issue we can iterate further. I'm also not certain how Lerna and its version checks will work with what was proposed but this should be something we will learn ourselves pretty soon. I'm not concerned at all about major WordPress releases and sync from |
docs/contributors/release.md Outdated
|
||
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. |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
youknowriad
Mar 5, 2019
Author
Contributor
I prefer to keep it here, as it's important to read and stop the process if trunk
is not open yet.
|
||
- During the `beta` and the `RC` period of the WordPress release cycle. | ||
- For WordPress minor releases and WordPress security releases (example `5.1.1`). | ||
|
This comment has been minimized.
This comment has been minimized.
gziolo
Mar 4, 2019
Member
Should This can happen...
part be moved after the list of steps to make it easier to follow?
This comment has been minimized.
This comment has been minimized.
youknowriad
Mar 5, 2019
Author
Contributor
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.
youknowriad commentedFeb 27, 2019
This PR updates the npm packages release process to match yesterday's discussion in the #core-js meeting.
See https://make.wordpress.org/core/2019/02/26/javascript-chat-summary-february-26th-2019/