Docs: Extend guidelines for managing packages and publishing them to …

…npm (#8768)

* Docs: Extend guidelines for publishing packages to npm

* Docs: Add details about creating new package

* Add React Native entrypoint in example package.json

* Docs: Add managing packages section

* Docs: Tiny fix in CONTRIBUTING.md file

* Docs: Tiny title fix in CONTRIBUTING.md file

* Minor verbiage tweak to _Major version_ semver

* Revert accidental changes added in 3a034a1

* docs: Make `npm` consistent and tweak a few things

* docs: Tweaks for readability, typo fixes, etc.

* Use

* Update CONTRIBUTING.md

Added @aduth suggestion from the core JS chat: https://make.wordpress.org/core/2018/08/21/javascript-chat-summary-august-21/.

CONTRIBUTING.md

@@ -23,7 +23,7 @@ npx nvm install
 npx nvm use
 ```
 
-You should also have the latest release of <a href="https://npmjs.org">npm installed</a>, npm is a separate project from Node.js and is updated frequently. If you've just installed Node.js which includes a version of npm within the installation you most likely will need to also update your npm install. To update npm, type this into your terminal: `npm install npm@latest -g`
+You should also have the latest release of [npm installed][npm]. npm is a separate project from Node.js and is updated frequently. If you've just installed Node.js which includes a version of npm within the installation you most likely will need to also update your npm installation. To update npm, type this into your terminal: `npm install npm@latest -g`
 
 To test the plugin, or to contribute to it, you can clone this repository and build the plugin files using Node. How you do that depends on whether you're developing locally or uploading the plugin to a remote host.
 
@@ -109,45 +109,131 @@ The workflow is documented in greater detail in the [repository management](./do
 
 Gutenberg contains both PHP and JavaScript code, and encourages testing and code style linting for both. It also incorporates end-to-end testing using [Google Puppeteer](https://developers.google.com/web/tools/puppeteer/). You can find out more details in [Testing Overview document](./docs/reference/testing-overview.md).
 
-## Releasing packages
+## Managing packages
+
+This repository uses [lerna] to manage Gutenberg modules and publish them as packages to [npm]. 
+
+### Creating new package
+
+When creating a new package you need to provide at least the following:
+
+1. `package.json` based on the template:
+	```json
+	{
+		"name": "@wordpress/package-name",
+		"version": "1.0.0-beta.0",
+		"description": "Package description.",
+		"author": "The WordPress Contributors",
+		"license": "GPL-2.0-or-later",
+		"keywords": [
+			"wordpress"
+		],
+		"homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/package-name/README.md",
+		"repository": {
+			"type": "git",
+			"url": "https://github.com/WordPress/gutenberg.git"
+		},
+		"bugs": {
+			"url": "https://github.com/WordPress/gutenberg/issues"
+		},
+		"main": "build/index.js",
+		"module": "build-module/index.js",
+		"react-native": "src/index",
+		"dependencies": {
+			"@babel/runtime-corejs2": "7.0.0-beta.56"
+		},
+		"publishConfig": {
+			"access": "public"
+		}
+	}
+	```
+	This assumes that your code is located in the `src` folder and will be transpiled with `Babel`.
+2. `.npmrc` file which disables creating `package-lock.json` file for the package:
+	```
+	package-lock=false
+	```
+3. `README.md` file containing at least:
+	- Package name
+	- Package description
+	- Installation details
+	- Usage example
+	- `Code is Poetry` logo (`<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>`)
+
+### Maintaining changelogs
+
+Maintaining dozens of npm packages is difficult—it can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. All packages should follow the [Semantic Versioning (`semver`) specification](https://semver.org/).
+
+The developer who proposes a change (pull request) is responsible to choose the correct version increment (`major`, `minor`, or `patch`) according to the following guidelines:
+
+- Major version X (X.y.z | X > 0) should be changed with any backwards-incompatible/"breaking" change. This will usually occur at the final stage of deprecating and removing of a feature.
+- Minor version Y (x.Y.z | x > 0) should be changed when you add functionality or change functionality in a backwards-compatible manner. It must be incremented if any public API functionality is marked as deprecated.
+- Patch version Z (x.y.Z | x > 0) should be incremented when you make backwards-compatible bug fixes.
 
-This repository uses [lerna](https://lernajs.io) to manage Gutenberg modules and publish them as packages to `npm`. Lerna automatically releases all the outdated packages. To check which packages are outdated and will be released, type `npm run publish:check`.
+When in doubt, refer to [Semantic Versioning specification](https://semver.org/).
 
-If you have the ability to publish packages, you _must_ have [2FA enabled](https://docs.npmjs.com/getting-started/using-two-factor-authentication) on your npmjs.com account.
+_Example:_
+
+```md
+## v1.2.2 (Unreleased)
+
+### Bug Fix
+
+- ...
+- ...
+```
 
-### Before releasing
+- If you need to add something considered a bug fix, you add the item to `Bug Fix` section and leave the version as 1.2.2.
+- If it's a new feature you add the item to `New Feature` section and change version to 1.3.0.
+- If it's a breaking change you want to introduce, add the item to `Breaking Change` section and bump the version to 2.0.0.
+- If you struggle to classify a change as one of the above, then it might be not necessary to include it.
 
-Confirm that you're logged into `npm`, by running `npm whoami`. If you're not logged in, run `npm adduser` to login.
+The version bump is only necessary if one of the following applies:
+ - There are no other unreleased changes.
+ - The type of change you're introducing is incompatible (more severe) than the other unreleased changes.
+
+### Releasing packages
+
+Lerna automatically releases all outdated packages. To check which packages are outdated and will be released, type `npm run publish:check`.
+
+If you have the ability to publish packages, you _must_ have [2FA enabled](https://docs.npmjs.com/getting-started/using-two-factor-authentication) on your [npm account][npm].
+
+#### Before releasing
+
+Confirm that you're logged in to [npm], by running `npm whoami`. If you're not logged in, run `npm adduser` to login.
 
 If you're publishing a new package, ensure that its `package.json` file contains the correct `publishConfig` settings:
 
 ```json
+{
 	"publishConfig": {
 		"access": "public"
 	}
+}
 ```
 
-### Development release
+You can check your package configs by running `npm run lint-pkg-json`.
+
+#### Development release
 
-Run the following command to release a dev version of the outdated packages, replacing "123456" with your 2FA code. Make sure you're using a freshly generated 2FA code, rather than one that's about to timeout. This is a little cumbersome, but helps to prevent the release process from dying mid-deploy.
+Run the following command to release a dev version of the outdated packages, replacing `123456` with your 2FA code. Make sure you're using a freshly generated 2FA code, rather than one that's about to timeout. This is a little cumbersome, but helps to prevent the release process from dying mid-deploy.
 
 ```bash
 NPM_CONFIG_OTP=123456 npm run publish:dev
 ```
 
 Lerna will ask you which version number you want to choose for each package. For a `dev` release, you'll more likely want to choose the "prerelease" option. Repeat the same for all the outdated packages and confirm your version updates.
 
-Lerna will then publish to `npm`, commit the `package.json` changes and create the git tags.
+Lerna will then publish to [npm], commit the `package.json` changes and create the git tags.
 
-### Production release
+#### Production release
 
-To release a production version for the outdated packages, run the following command, replacing "123456" with your (freshly generated, as above) 2FA code:
+To release a production version for the outdated packages, run the following command, replacing `123456` with your (freshly generated, as above) 2FA code:
 
 ```bash
 NPM_CONFIG_OTP=123456 npm run publish:prod
 ```
 
-Choose the correct version (minor, major or patch) and confirm your choices and let Lerna do its magic.
+Choose the correct version based on `CHANGELOG.md` files, confirm your choices and let Lerna do its magic.
 
 ## How Designers Can Contribute
 
@@ -176,3 +262,6 @@ A Global Translation Editor (GTE) or Project Translation Editor (PTE) with suita
 Language packs are automatically generated once 95% of the plugin's strings are translated and approved for a locale.
 
 The eventual inclusion of Gutenberg into WordPress core means that more than 51% of WordPress installations running a translated WordPress installation will have Gutenberg's translated strings compiled into the core language pack as well.
+
+[lerna]: https://lernajs.io/
+[npm]: https://www.npmjs.com/

README.md

@@ -1,6 +1,7 @@
 # Gutenberg
 [![Build Status](https://img.shields.io/travis/WordPress/gutenberg/master.svg)](https://travis-ci.org/WordPress/gutenberg)
 [![Coverage](https://img.shields.io/codecov/c/github/WordPress/gutenberg/master.svg)](https://codecov.io/gh/WordPress/gutenberg)
+[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lernajs.io/)
 
 Printing since 1440.
 

docs/reference/repository-management.md

@@ -123,6 +123,7 @@ A pull request can generally be merged once it is:
 - In compliance with all relevant code review criteria.
 - Covered by sufficient tests, as necessary.
 - Vetted against all potential edge cases.
+- Changelog entries were properly added.
 - Reviewed by someone other than the original author.
 
 The final pull request merge decision is made by the **@wordpress/gutenberg-core** team.