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

Jump to bottom

docs: add standalone npm package release docs #19381

Merged
merged 4 commits into from
Jan 4, 2020
Merged

docs: add standalone npm package release docs #19381

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3d813d0
docs: add standalone npm package release docs
ntwb Jan 1, 2020
7ea2c44
Update docs/contributors/release.md
ntwb Jan 2, 2020
a722aed
Explicitly number list items
ntwb Jan 2, 2020
b64d0f8
Remove changelog version note
ntwb Jan 2, 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
122 changes: 122 additions & 0 deletions docs/contributors/release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -253,6 +253,128 @@ 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.

Note: Both the `master` and `wp/trunk` branches are restricted and can only be _pushed_ to by the Gutenberg Core team.

Identify the commit hashes from the pull requests that need to be ported from the repo `master` branch to `wp/trunk`

The `wp/trunk` branch now needs to be prepared to release and publish the packages to _npm_.

Open a terminal and perform the following steps:
1. `git checkout master`
2. `git pull`
3. `git checkout wp/trunk`
4. `git pull`

Before porting commits check that the `wp/trunk` branch does not have any outstanding packages waiting to be published:
1. `git checkout wp/trunk`
2. `npm run publish:check`

Now _cherry-pick_ the commits from `master` to `wp/trunk`, use `-m 1 commithash` if the commit was a pull request merge commit:
1. `git cherry-pick -m 1 cb150a2`
2. `git push`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally push only specific branches, is it always safe to use git push with the current branch?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only @WordPress/gutenberg-core can push to either of those branches directly I believe, so some care should be taken, and it's not ideal

This entire workflow outlined could be refactored to create branches off of wp/trunk then create PRs back against that branch, probably worth doing in a follow up PR

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, branching could work, although it's easier to apply commits one by one directly in the wp/trunk branch. We do it the same way in master when backporting publish and changelog changes.

FYI, I started automation around npm publish workflow when syncing plugin with wp/trunk:

gutenberg/bin/commander.js

Lines 704 to 730 in 431f76c

async function runWordPressReleaseBranchSyncStep( abortMessage ) {
const wordpressReleaseBranch = 'wp/trunk';
await runStep( 'Getting into the WordPress release branch', abortMessage, async () => {
const simpleGit = SimpleGit( gitWorkingDirectoryPath );
const packageJsonPath = gitWorkingDirectoryPath + '/package.json';
const pluginReleaseBranch = findReleaseBranchName( packageJsonPath );
// Creating the release branch
await simpleGit.checkout( wordpressReleaseBranch );
console.log( '>> The local release branch ' + success( wordpressReleaseBranch ) + ' has been successfully checked out.' );
await askForConfirmationToContinue(
`The branch is ready for sync with the latest plugin release changes applied to "${ pluginReleaseBranch }". Proceed?`,
true,
abortMessage
);
await simpleGit.raw( [ 'rm', '-r', '.' ] );
await simpleGit.raw( [ 'checkout', `origin/${ pluginReleaseBranch }`, '--', '.' ] );
await simpleGit.commit( `Merge changes published in the Gutenberg plugin "${ pluginReleaseBranch }" branch` );
console.log( '>> The local WordPress release branch ' + success( wordpressReleaseBranch ) + ' has been successfully synced.' );
} );
return {
releaseBranch: wordpressReleaseBranch,
};
}

It's still in progress and needs more work though.


Whilst waiting for the Travis CI build for `wp/trunk` [branch to pass](https://travis-ci.com/WordPress/gutenberg/branches) identify and begin updating the `CHANGELOG.md` files:
1. `git checkout wp/trunk`
2. `npm run publish:check`
> Example
> ```shell
> npm run publish:check
> @wordpress/e2e-tests
> @wordpress/jest-preset-default
> @wordpress/scripts
> lerna success found 3 packages ready to publish
> ```

Check the versions listed in the current `CHANGELOG.md` file, looking through the commit history of a package e.g [@wordpress/scripts](https://github.com/WordPress/gutenberg/commits/master/packages/scripts) and look out for _"chore(release): publish"_ and _"Update changelogs"_ commits to determine recent version bumps, then looking at the commits since the most recent release should aid with discovering what changes have occurred since the last release.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In theory, PRs should cover that part, but in reality, there is only a handful of people who do it. I guess the section about updating changelogs and picking the proper version bump is common for all types of npm releases.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

True, semantic-release, there's a Lerna semantic release even, but getting to that stage whilst still making it easy for contributors is the hard part.

We could start enforcing (via GitHub) actions that changelogs are updated, but again, that's not the easiest for contributors (its hard and time consuming for experienced contributors)


Note: You may discover the current version of each package is not up to date, if so updating the previous released versions would be appreciated.

Begin updating the _changelogs_ based on the [Maintaining Changelogs](https://github.com/WordPress/gutenberg/blob/master/packages/README.md#maintaining-changelogs) documentation and commit the changes:

1. `git checkout wp/trunk`
2. Update each of the `CHANGELOG.md` files
3. Stage the _changelog_ changes `git add packages/`
4. `git commit -m "Update changelogs"`
5. Make a note of the commit hash of this commit
> Example
> ```
> [master 278f524f16] Update changelogs` 278f524
> ```
6. `git push`

Now that the changes have been committed to the `wp/trunk` branch and the Travis CI builds for the `wp/trunk` [branch are passing](https://travis-ci.com/WordPress/gutenberg/branches) it's time to publish the packages to npm:
1. Once again run `npm run publish:check` to confirm there are no unexpected packages ready to be published:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this step is necessary at this point. CHANGELOG files are ignored by Lerna.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, but whilst cherry-picking between master and wp/trunk it's a nice safeguard to ensure you haven't cherry-picked and incorrect commit that would result in another package up for release 😏

Personally, as I was doing just that I wanted to make sure as I did each of the steps I documented the steps, I also did this over the course of ~2 days, an hour here, an hour there, so re-running these steps git pull, git status, npm run publish:check ensured I had not made a mistake 😬

> Example
> ```shell
> npm run publish:check
> @wordpress/e2e-tests
> @wordpress/jest-preset-default
> @wordpress/scripts
> lerna success found 3 packages ready to publish
> ```
2. Run the [package release process](https://github.com/WordPress/gutenberg/blob/master/packages/README.md#releasing-packages) but when asked for the version numbers to choose for each package use the versions you made note of above when updating each packages `CHANGELOG.md` file.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, from now on, it's all common for all release types. It's fine as is, but we can cross-link it later to make it easier to follow for folks.

> Truncated example of publishing process output
> ```
> npm run publish:prod
>
> Build Progress: [==============================] 100%
> lerna notice cli v3.18.2
> lerna info versioning independent
> ? Select a new version for @wordpress/e2e-tests (currently 1.9.0) Patch (1.9.1)
> ? Select a new version for @wordpress/jest-preset-default (currently 5.3.0) Patch (5.3.1)
> ? Select a new version for @wordpress/scripts (currently 6.1.0) Patch (6.1.1)
>
> Changes:
> - @wordpress/e2e-tests: 1.9.0 => 1.9.1
> - @wordpress/jest-preset-default: 5.3.0 => 5.3.1
> - @wordpress/scripts: 6.1.0 => 6.1.1
>
> ? Are you sure you want to publish these packages? Yes
> lerna info execute Skipping releases
> lerna info git Pushing tags...
> lerna info publish Publishing packages to npm...
> lerna info Verifying npm credentials
> lerna info Checking two-factor auth mode
> ? Enter OTP: 753566
> lerna success published @wordpress/jest-preset-default 5.3.1
> lerna success published @wordpress/scripts 6.1.1
> lerna success published @wordpress/e2e-tests 1.9.1
> Successfully published:
> - @wordpress/e2e-tests@1.9.1
> - @wordpress/jest-preset-default@5.3.1
> - @wordpress/scripts@6.1.1
> lerna success published 3 packages
> ```

Now that the packages have been published the _"chore(release): publish"_ and _"Update changelogs"_ commits to `wp/trunk` need to be ported to the `master` branch:
1. `git checkout master`
2. `git pull`
3. Cherry-pick the `278f524`hash you noted above from the _"Update changelogs"_ commit made to `wp/trunk`
4. `git cherry-pick 278f524`
5. Get the commit hash from the the lerna publish commit either from the terminal or [wp/trunk commits](https://github.com/WordPress/gutenberg/commits/wp/trunk)
6. Cherry-pick the `fe6ae0d` "chore(release): publish"_ commit made to `wp/trunk`
7. `git cherry-pick fe6ae0d`
8. `git push`

Confirm the packages dependancies do not contain `file://` links in the `dependencies` or `devdependencies` section of the packages released, e.g:
> https://unpkg.com/browse/@wordpress/jest-preset-default@5.3.1/package.json
> https://unpkg.com/browse/@wordpress/scripts@6.1.1/package.json
> https://unpkg.com/browse/@wordpress/jest-preset-default@5.3.1/package.json

Time to announce the published changes in the #core-js and #core-editor Slack channels
> ```
> 📣 Successfully published:
> • @wordpress/e2e-tests@1.9.1
> • @wordpress/jest-preset-default@5.3.1
> • @wordpress/scripts@6.1.1
> Lerna success published 3 packages
```

---------

Ta-da! 🎉
Expand Down