Thanks for your interest in contributing to WooCommerce Blocks! Below are some developer docs for working with the project.
To get started, first run `npm install` and `composer install`.
## npm scripts
We have a set of scripts in npm to handle repeated developer tasks.
### `build` & `start`
These scripts compile the code using `webpack`. Run `build` to build the production build, `start` to build the development build and then keep watching for changes. You can also run `npx webpack` to run the development build and not keep watching.
### `lint`
This script runs 3 sub-commands: `lint:php`, `lint:css`, `lint:js`. Use these to run linters across the codebase.
-`lint:php` runs phpcs via composer, which uses the [phpcs.xml](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/master/phpcs.xml) ruleset.
-`lint:css` runs stylelint over all the scss code in `assets/css`, using the rules in [.stylelintrc.json.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/master/.stylelintrc.json)
-`lint:js` runs eslint over all the JavaScript, using the rules in [.eslintrc.js.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/blob/master/.eslintrc.js)
### `test`
The test scripts use [wp-scripts](https://github.com/WordPress/gutenberg/tree/master/packages/scripts) to run jest for component and unit testing.
-`test:update` updates the snapshot tests for components, used if you change a component that has tests attached.
- Use `test:watch` to keep watch of files and automatically re-run tests.
### `prepack`
This script is run automatically when `npm pack` or `npm publish` is run. It installs packages, runs the linters, runs the tests, and then builds the files from the source once more.
## Publishing @woocommerce/block-library
We publish the blocks to npm at [@woocommerce/block-library,](https://www.npmjs.com/package/@woocommerce/block-library) and then import them into WooCommerce core via [a grunt script.](https://github.com/woocommerce/woocommerce/blob/741bd5ba6d193e21893ef3af3d4f3f030a79c099/Gruntfile.js#L347)
To release a new version, there are 3 basic steps. Prepare and test the release, publish the version, then import into WooCommerce core.
### Prepare and test the release
- Manually change the versions in `package.json` and `woocommerce-gutenberg-products-block.php` (once in the plugin header, and `WGPB_VERSION`). [See an example PR with these changes.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/pull/478/commits/725c43fe0362044c953728cb3391095a43e66bb5)
- Run `npm pack` to prep a `.tgz` file.
- Optionally test the package by uploading this onto a test site.
### Publish this version
On GitHub…
- go to [Releases](https://github.com/woocommerce/woocommerce-gutenberg-products-block/releases) and click "Draft a new release"
- The Tag version should start with `v`, and use [semver](https://semver.org/) formatting, ex `v2.0.0-rc`, or `v1.4.1`
- The Release title should be the human-readable version, ex "2.0.0 Release Candidate" or "2.0.0 alpha release"
- Add the changelog to the description (TBD, maybe not for every release?)
- Upload the `.tgz` from `npm pack` in the previous step as an attached binary
On npm…
- Run `npm publish --access public`, which will push the version up to npm.
- Check [@woocommerce/block-library](https://www.npmjs.com/package/@woocommerce/block-library) for your update
### Pull into WooCommerce core
- Manually update the @woocommerce/block-library version in `package.json`
- In the woocommerce folder, run `npm install` to download the version you just specified
- Run the copy command, `npx grunt blocks`, to copy the build files from node_modules into their destinations in WC core
- Check that the changes imported look correct
- Make a PR on WooCommerce to import the new version
## How to test `@woocommerce/block-library` without publishing to npm
If you need to test how something works once built into WooCommerce core, you can `pack` a .tgz file and tell WooCommerce to use this local .tgz file instead of the version on npmjs.com.
- Run `npm pack` to create the .tgz file
- Move the file into the `woocommerce` plugin directory, optionally renaming it to something unique
- Now you can run `npm install` in woocommerce to install from this local file
- Run `npx grunt blocks` to build just the blocks code, or `npx grunt` to run the full build process
- Test whatever you were testing 🎉
If you're testing something multiple times, note that the **.tgz is cached,** so if you're doing this more than once, the tgz name needs to be different to break that cache.
