Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Handbook: udpate docs for package release #23162

Merged
merged 5 commits into from
Jun 15, 2020
Merged

Handbook: udpate docs for package release #23162

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
46853cf
Udpate docs for package release
oandregal Jun 15, 2020
79ac541
Add note about use of OTP
oandregal Jun 15, 2020
1805a5a
Add note about npm org
oandregal Jun 15, 2020
3708d98
Add note about lerna publish from-package
oandregal Jun 15, 2020
be4816c
Update docs/contributors/release.md
nosolosw Jun 15, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 23 additions & 20 deletions docs/contributors/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This Repository is used to perform several types of releases. This document serves as a checklist for each one of these. It is helpful if you'd like to understand the different workflows.

To release Gutenberg, you need commit access to the [WordPress.org plugin repository][plugin repository]. 🙂
To release Gutenberg, you need commit access to the [WordPress.org plugin repository][plugin repository] as well as being part of the [WordPress organization at npm](https://www.npmjs.com/org/wordpress). 🙂

## Plugin Releases

Expand Down Expand Up @@ -166,7 +166,6 @@ Creating a release involves:
8. Push the tag `git push --tags`.
9. Merge the version bump pull request.


##### Build the Plugin

1. Run `git fetch --tags`.
Expand Down Expand Up @@ -228,38 +227,43 @@ If you don't have access to [make.wordpress.org/core](https://make.wordpress.org

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 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 WordPress `trunk` branch is marked as "feature-freezed". (This usually happens when the first `beta` of the next WordPress major version is released).
- The `wp/trunk` branch contains all the packages that are published and used in the `trunk` branch of WordPress.
- 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 WordPress `trunk` branch is marked as "feature-freezed". (This usually happens when the first `beta` of the next WordPress major version is released).

### Synchronizing WordPress Trunk

For each Gutenberg plugin release, WordPress trunk should be synchronized with this release. This involves the following steps that are automated with `./bin/plugin/cli npm-stable` command:
For each Gutenberg plugin release, WordPress trunk should be synchronized. Note that 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.

The process has three steps: 1) update the `wp/trunk` branch within the Gutenberg repo 2) publish the new package versions to npm 3) update the WordPress `trunk` branch.

**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.
The first step is automated via `./bin/plugin/cli.js npm-stable` command. You only have to run the command, but, for the record, the manual process would look like this:

1. Ensure the WordPress `trunk` branch is open for enhancements.
2. Get the last published Gutenberg release branch with `git fetch`.
2. Check out the `wp/trunk` branch.
3. Remove all files from the current branch: `git rm -r .`.
4. Check out all the files from the release branch: `git checkout release/x.x -- .`.
5. Commit all changes to the `wp/trunk` branch with `git commit -m "Merge changes published in the Gutenberg plugin vX.X release"` and push to the repository.
6. Update the `CHANGELOG.md` files of the packages with the new publish version calculated and commit to the `wp/trunk` branch.
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 in case of `minor` version.
3. Check out the `wp/trunk` branch.
4. Remove all files from the current branch: `git rm -r .`.
5. Check out all the files from the release branch: `git checkout release/x.x -- .`.
6. Commit all changes to the `wp/trunk` branch with `git commit -m "Merge changes published in the Gutenberg plugin vX.X release"` and push to the repository.
7. Update the `CHANGELOG.md` files of the packages with the new publish version calculated and commit to the `wp/trunk` branch. 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 in case of `minor` version.

Now, the branch is ready to be used to publish the npm packages.
Once the command is finished, you can start the second part: publishing the npm packages.

1. Run the [package release process] but when asked for the version numbers to choose for each package pick values based on the updated CHANGELOG files.
2. 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 committed into WordPress `trunk`.
1. Update your local `wp/trunk` branch with the latest changes pushed to GitHub.
2. Log-in to npm via the console: `npm login`. Note that you should have 2FA enabled.
3. From the `wp/trunk` branch, run the script `npm run publish:prod`.
- When asked for the version numbers to choose for each package pick the values of the updated CHANGELOG files.
- You'll be asked for your One-Time Password (OTP) a couple of times. This is the code from the 2FA authenticator app you use. Depending on how many packages are to be released you may be asked for more than one OTP, as they tend to expire before all packages are released.
- If the publishing process ends up incomplete (perhaps because it timed-out or an bad OTP was introduce) you can resume it via [`lerna publish from-package`](https://github.com/lerna/lerna/tree/master/commands/publish#bump-from-package).
4. Cherry-pick the commits created by lerna ("Publish" and the CHANGELOG update) into the `master` branch of Gutenberg.

Finally, now that the npm packages are ready, a patch can be created and committed into WordPress `trunk`.

### 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:

- During the `beta` and the `RC` period of the WordPress release cycle.
- For WordPress minor releases and WordPress security releases (example `5.1.1`).
- During the `beta` and the `RC` period of the WordPress release cycle.
- For WordPress minor releases and WordPress security releases (example `5.1.1`).

1. Cherry-pick
2. Check out the last published Gutenberg release branch `git checkout release/x.x`
Expand All @@ -278,7 +282,6 @@ Now, the branch is ready to be used to publish the npm packages.

Now, the npm packages should be ready and a patch can be created and committed into the corresponding WordPress SVN branch.


### Standalone Package Releases

The following workflow is needed when packages require bug fixes or security releases to be published to _npm_ outside of a WordPress release cycle.
Expand Down