docs: add standalone npm package release docs #19381

ntwb · 2020-01-01T23:39:12Z

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

aduth · 2020-01-02T16:57:15Z

docs/contributors/release.md

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


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.

Makes sense, removed this in b64d0f8

docs/contributors/release.md

aduth · 2020-01-02T17:00:53Z

docs/contributors/release.md

+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


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.

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

Co-Authored-By: Andrew Duthie <andrew@andrewduthie.com>

gziolo · 2020-01-03T07:27:34Z

docs/contributors/release.md

+
+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` 


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

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

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.

gziolo · 2020-01-03T07:32:40Z

docs/contributors/release.md

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


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.

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)

gziolo · 2020-01-03T07:34:00Z

docs/contributors/release.md

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


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

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 😬

gziolo · 2020-01-03T07:37:16Z

docs/contributors/release.md

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


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 · 2020-01-03T07:39:43Z

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

docs: add standalone npm package release docs

3d813d0

ntwb added [Type] Developer Documentation Documentation for developers npm Packages Related to npm packages [Type] Project Management Meta-issues related to project management of Gutenberg labels Jan 1, 2020

ntwb requested review from youknowriad, gziolo and aduth January 1, 2020 23:39

ntwb requested review from ajitbohra and chrisvanpatten as code owners January 1, 2020 23:39

ntwb mentioned this pull request Jan 1, 2020

Improve the workflow for publishing packages to npm #11780

Closed

aduth reviewed Jan 2, 2020

View reviewed changes

ntwb and others added 3 commits January 3, 2020 09:10

Update docs/contributors/release.md

7ea2c44

Co-Authored-By: Andrew Duthie <andrew@andrewduthie.com>

Explicitly number list items

a722aed

Remove changelog version note

b64d0f8

gziolo reviewed Jan 3, 2020

View reviewed changes

gziolo approved these changes Jan 3, 2020

View reviewed changes

ntwb merged commit d502949 into master Jan 4, 2020

ntwb deleted the update/release-docs branch January 4, 2020 03:25

youknowriad added this to the Gutenberg 7.2 milestone Jan 6, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add standalone npm package release docs #19381

docs: add standalone npm package release docs #19381

ntwb commented Jan 1, 2020

aduth Jan 2, 2020

ntwb Jan 2, 2020

aduth Jan 2, 2020

ntwb Jan 2, 2020

gziolo Jan 3, 2020

ntwb Jan 3, 2020

gziolo Jan 3, 2020

gziolo Jan 3, 2020

ntwb Jan 3, 2020

gziolo Jan 3, 2020

ntwb Jan 3, 2020

gziolo Jan 3, 2020

gziolo commented Jan 3, 2020

	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,
	};
	}

docs: add standalone npm package release docs #19381

docs: add standalone npm package release docs #19381

Conversation

ntwb commented Jan 1, 2020

Description

How has this been tested?

Screenshots

Types of changes

Checklist:

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo commented Jan 3, 2020