diff --git a/readme.md b/readme.md index 761395332caec..e505f389c346a 100644 --- a/readme.md +++ b/readme.md @@ -40,21 +40,32 @@ Developers of all levels can help — whether you can barely recognize a filter The javascript and CSS components of this plugin's admin interface need to be built in order to get the runtime bundle (`_inc/build/admin.js`) -**Recommended Dependencies** +**Recommended Environment** -Recommended environment: -- Node 6.x -- npm 3.8.x +* Node 6.x +* npm 3.8.x -If you're having trouble installing 6.x, [nvm](https://www.npmjs.com/package/nvm) is a nice tool for node version management :) +#### A note on Node versions used for the build tasks + +We try to frequently keep the Node version we use up to date. So, eventually you may need to refresh your package dependencies (i.e., the `node_modules` directories). This is because some dependencies are built specifically for the Node version you used when you installed them (either by running `npm run build` or `npm install`). + +We recommend usage of [nvm](https://www.npmjs.com/package/nvm) for managing different Node versions on the same environment. + +**Note:** If you have previously run the Jetpack build tasks (e.g. `npm run build`), and didn't come back to it for a long time, you can +run this command before building again. Otherwise you may experience errors on the command line while trying to build. + +``` +$ npm run distclean +``` **Start Development** 1. Make sure you have `git`, `node`, and `npm` installed and a working WordPress installation. -2. Clone this repository locally inside your `/wp-content/plugins` directory. +2. Clone this repository inside your Plugins directory. ``` - git clone https://github.com/Automattic/jetpack.git + $ git clone https://github.com/Automattic/jetpack.git + $ cd jetpack ``` 3. Install [yarn](https://www.npmjs.com/package/yarn) package. @@ -65,47 +76,44 @@ If you're having trouble installing 6.x, [nvm](https://www.npmjs.com/package/nvm 4. Make sure the Jetpack plugin is active and run ``` - npm run build + $ npm run build ``` This will install npm dependencies and then build the files. 5. Open `/wp-admin/admin.php?page=jetpack` in your browser. -#### Production build - -The production build will generate minified files without duplicated code (resulting from dependencies) and also will generate the matching sourcemap files and language files. - -``` -npm run build-production -``` - #### Development build -The development build will create a build without minifying or deduping code. +The development build will create a build without minifying or deduping code. It will also install dependencies for you, so you don't need to `npm install` before it. ``` -npm run build +$ npm run build ``` #### Development build with changes monitoring (watch) -Running `npm run watch` instead of `npm run build` will build all the code and continuously watch the front-end JS and CSS/Sass for changes and rebuild accordingly. - -**Before running `npm run watch` you may need to `npm install` the npm dependencies first if you didn't do it already**. +You can ran a watch process which will continuously watch the front-end JS and CSS/Sass for changes and rebuild accordingly. +Instead of `npm run build` you'd use `npm run watch`. -Clone this repository inside your Plugins directory. +Before running the watch process you may need to `npm install` the npm dependencies first if you didn't do it already. ``` -$ git clone git@github.com:Automattic/jetpack.git -$ cd jetpack $ npm install $ npm run watch ``` +#### Production build + +The production build will generate minified files without duplicated code (resulting from dependencies) and also will generate the matching sourcemap files and language files. + +``` +$ npm run build-production +``` + #### Unit-testing the JS Admin Page -You can run [Mocha](https://mochajs.org/) based tests for the Admin Page source code with `npm run test-client` +You can run [Mocha](https://mochajs.org/) based tests for the Admin Page source code. Standing on your jetpack directory, run