woocommerce/plugins/woocommerce-blocks/CONTRIBUTING.md

4.8 KiB

Contributing

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 ruleset.
  • lint:css runs stylelint over all the scss code in assets/css, using the rules in .stylelintrc.json.
  • lint:js runs eslint over all the JavaScript, using the rules in .eslintrc.js.

test

The test scripts use wp-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, and then import them into WooCommerce core via a grunt script.

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.
  • 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 and click "Draft a new release"
  • The Tag version should start with v, and use semver 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…

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

Publishing the WooCommerce Blocks plugin

TBD

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
  • Update /woocommerce/package.json:
"dependencies": {
  "@woocommerce/block-library": "file://./woocommerce-block-library-2.2.0-dev.tgz"
},
  • 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.