docs: add standalone npm package release docs

[ntwb]

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]

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.

[ntwb]

Makes sense, removed this in b64d0f8

[aduth]

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.

[ntwb]

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

[gziolo]

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

[ntwb]

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

[gziolo]

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]

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.

[ntwb]

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]

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

[ntwb]

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]

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]

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