From db23b8c4abeb6c8711060e78cfbab1648ad7f27a Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Tue, 6 Aug 2019 11:31:01 +0200 Subject: [PATCH] Docs: Clarify how to update a dependency for existing packages --- packages/README.md | 52 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 41 insertions(+), 11 deletions(-) diff --git a/packages/README.md b/packages/README.md index b5296fa094b3d..3937b7adee5a3 100644 --- a/packages/README.md +++ b/packages/README.md @@ -1,8 +1,8 @@ -## Managing Packages +# Managing Packages This repository uses [lerna] to manage WordPress modules and publish them as packages to [npm]. -### Creating a New Package +## Creating a New Package When creating a new package, you need to provide at least the following: @@ -48,13 +48,17 @@ When creating a new package, you need to provide at least the following: - Usage example - `Code is Poetry` logo (`

Code is Poetry.

`) -### Adding New Dependencies +## Managing Dependencies There are two types of dependencies that you might want to add to one of the existing WordPress packages. -#### Production Dependencies +### Production Dependencies -Production dependencies are stored in the `dependencies` section of the package’s `package.json` file. The simplest way to add such a dependency to one of the packages is to run a very convenient [lerna add](https://github.com/lerna/lerna/tree/master/commands/add#readme) command from the root of the project. +Production dependencies are stored in the `dependencies` section of the package’s `package.json` file. + +#### Adding New Dependencies + +The simplest way to add a production dependency to one of the packages is to run a very convenient [lerna add](https://github.com/lerna/lerna/tree/master/commands/add#readme) command from the root of the project. _Example:_ @@ -64,7 +68,33 @@ lerna add lodash packages/a11y This command adds the latest version of `lodash` as a dependency to the `@wordpress/a11y` package, which is located in `packages/a11y` folder. -#### Development Dependencies +#### Removing Existing Dependencies + +Removing a dependency from one of the WordPress packages requires some manual work. You need to remove the line in the corresponding `dependencies` section of the `package.json` file. + +_Example:_ + +```diff ++++ b/packages/scripts/package.json +@@ -43,7 +43,6 @@ + "check-node-version": "^3.1.1", + "cross-spawn": "^5.1.0", + "eslint": "^5.16.0", +- "jest": "^24.7.1", + "jest-puppeteer": "^4.0.0", + "minimist": "^1.2.0", + "npm-package-json-lint": "^3.6.0", +``` + +Next, you need to run `npm install` in the root of the project to ensure that `package-lock.json` file gets properly regenerated. + +#### Updating Existing Dependencies + +This is the most confusing part of working with [lerna] which causes a lot of hassles for contributors. The most successful strategy so far is to do the following: + 1. First, remove the existing dependency as described in the previous section. + 2. Next, add the same dependency back as described in the first section of this chapter. This time it wil get the latest version applied unless you enforce a different version explicitly. + +### Development Dependencies In contrast to production dependencies, development dependencies shouldn't be stored in individual WordPress packages. Instead they should be installed in the project's `package.json` file using the usual `npm install` command. In effect, all development tools are configured to work with every package at the same time to ensure they share the same characteristics and integrate correctly with each other. @@ -76,7 +106,7 @@ npm install glob --save-dev This commands adds the latest version of `glob` as a development dependency to the `package.json` file. It has to be executed from the root of the project. -### Maintaining Changelogs +## Maintaining Changelogs In maintaining dozens of npm packages, it can be tough to keep track of changes. To simplify the release process, each package includes a `CHANGELOG.md` file which details all published releases and the unreleased ("Master") changes, if any exist. @@ -106,13 +136,13 @@ When in doubt, refer to [Semantic Versioning specification](https://semver.org/) If you are publishing new versions of packages, note that there are versioning recommendations outlined in the [Gutenberg Release Process document](https://github.com/WordPress/gutenberg/blob/master/docs/contributors/release.md) which prescribe _minimum_ version bumps for specific types of releases. The chosen version should be the greater of the two between the semantic versioning and Gutenberg release minimum version bumps. -### Releasing Packages +## 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 +### 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. @@ -128,7 +158,7 @@ If you're publishing a new package, ensure that its `package.json` file contains You can check your package configs by running `npm run lint-pkg-json`. -#### Development Release +### Development Release Run the following command to release a dev version of the outdated packages. @@ -140,7 +170,7 @@ Lerna will ask you which version number you want to choose for each package. For 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: