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.

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

Already on GitHub? Sign in to your account

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

merged 4 commits into from Jan 4, 2020

Conversation

@ntwb
Copy link
Member

ntwb commented Jan 1, 2020

Description

This pull requests adds a new section to the Packages Releases and WordPress Core Updates documentation detailing the steps required to publish packages to npm outside of a WordPress release.

How has this been tested?

Documentation was written during the process of releasing packages to npm 馃

Screenshots

Types of changes

Docs

Checklist:

  • My code is tested.
  • My code follows the WordPress code style.
  • My code follows the accessibility standards.
  • My code has proper inline documentation.
  • I've included developer documentation if appropriate.
  • I've updated all React Native files affected by any refactorings/renamings in this PR. .

1. `git checkout wp/trunk`
1. Update each of the `CHANGELOG.md` files
1. Make a note of each packages new version, you will require these when it comes time to publish the packages with Lerna to npm:

This comment has been minimized.

Copy link
@aduth

aduth Jan 2, 2020

Member

What does it mean here to "make a note of" ? Based on the previous statement of updating changelogs based on the "Maintaining Changelogs" documentation, we're not expecting the changelog for latest changes to be assigned with a specific version. If the releaser happens to be familiar with semantic versioning, they might understand what it would be expected to be (likely a patch bump based on the use-case for this release process), but that's not explicitly documented.

This comment has been minimized.

Copy link
@ntwb

ntwb Jan 2, 2020

Author Member

Makes sense, removed this in b64d0f8

docs/contributors/release.md Outdated Show resolved Hide resolved
5. Stage the _changelog_ changes `git add packages/`
1. `git commit -m "Update changelogs"`
1. Make a note of the commit hash of this commit
Comment on lines 308 to 310

This comment has been minimized.

Copy link
@aduth

aduth Jan 2, 2020

Member

Did you intend to number the list like this? The Markdown processor seems to tolerate it just as well and I could see how it makes it simpler to maintain, but there's an odd exception of the 5. here, and it's also less readable in the raw markdown form.

This comment has been minimized.

Copy link
@ntwb

ntwb Jan 2, 2020

Author Member

I did actually do this intentionally, I've been writing a lot of markdown lists recently, but it should be 4 nonetheless 馃槵

Also, as the w.org handbooks doesn't support this type of list format I will update those to 4,5,6.

Updated in a722aed

ntwb and others added 3 commits Jan 2, 2020
Co-Authored-By: Andrew Duthie <andrew@andrewduthie.com>

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`

This comment has been minimized.

Copy link
@gziolo

gziolo Jan 3, 2020

Member

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

This comment has been minimized.

Copy link
@ntwb

ntwb Jan 3, 2020

Author Member

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

This comment has been minimized.

Copy link
@gziolo

gziolo Jan 3, 2020

Member

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.

> 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.

This comment has been minimized.

Copy link
@gziolo

gziolo Jan 3, 2020

Member

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.

This comment has been minimized.

Copy link
@ntwb

ntwb Jan 3, 2020

Author Member

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)

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:

This comment has been minimized.

Copy link
@gziolo

gziolo Jan 3, 2020

Member

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

This comment has been minimized.

Copy link
@ntwb

ntwb Jan 3, 2020

Author Member

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 馃槵

> @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.

This comment has been minimized.

Copy link
@gziolo

gziolo Jan 3, 2020

Member

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.

@gziolo

This comment has been minimized.

Copy link
Member

gziolo commented Jan 3, 2020

@ntwb, great work documenting the process. It's much more detailed than we had before, so it should be very helpful for people going through the process for the first time. As noted, some parts are common for very workflow which publishes packages to npm but we can cross-link it later.

@gziolo
gziolo approved these changes Jan 3, 2020
@ntwb ntwb merged commit d502949 into master Jan 4, 2020
2 checks passed
2 checks passed
pull-request-automation
Details
Travis CI - Pull Request Build Passed
Details
@ntwb ntwb deleted the update/release-docs branch Jan 4, 2020
@youknowriad youknowriad added this to the Gutenberg 7.2 milestone Jan 6, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can鈥檛 perform that action at this time.