Skip to content

Latest commit

 

History

History
171 lines (133 loc) · 6.57 KB

CONTRIBUTING.md

File metadata and controls

171 lines (133 loc) · 6.57 KB

Contributing

Quick start 🚀

npm install
npm start

Build

  • npm run build - build H5Web for production
  • npm run storybook:build - build the component library's Storybook documentation site

Code quality

  • npm run lint - run all linting and code formatting commands
  • npm run lint:eslint - lint all TS and JS files with ESLint
  • npm run lint:tsc - type-check the whole project, test files included
  • npm run lint:prettier - check that all files have been formatted with Prettier
  • npm run analyze - inspect the size and content of the JS bundles (after npm run build)

Automatic fixing and formatting

  • npm run lint:eslint -- --fix - auto-fix linting issues
  • npm run lint:prettier -- --write - format all files with Prettier

Editor integration

Most editors support fixing and formatting files automatically on save. The configuration for VSCode is provided out of the box, so all you need to do is install the recommended extensions.

Testing

  • npm test - run unit and feature tests with Jest
  • npm run cypress - open the Cypress end-to-end test runner (local dev server must be running in separate terminal)
  • npm run cypress:run - run end-to-end tests once (local dev server must be running in separate terminal)
  • npm run storybook - manually test components in isolation in Storybook, at http://localhost:6006

Visual regression

Cypress is used for end-to-end testing but also for visual regression testing. The idea is to take a screenshot (or "snapshot") of the app in a known state and compare it with a previously approved "reference snapshot". If any pixel has changed, the test fails and a diff image highlighting the differences is created.

Taking consistent screenshots across platforms is impossible because the exact rendering of the app depends on the GPU. For this reason, visual regression tests are run only on the CI. This is done through an environment variable called CYPRESS_TAKE_SNAPSHOTS.

Visual regression tests may fail in the CI, either expectedly (e.g. when implementing a new feature) or unexpectedly (when detecting a regression). When this happens, the diff images and debug screenshots that Cypress generates are uploaded as artifacts of the workflow, which can be downloaded and reviewed.

If the visual regressions are expected, the version-controlled reference snapshots can be updated by posting a comment in the Pull Request with this exact text: /approve. This triggers the Approve snapshots workflow, which runs Cypress again but this time telling it to update the reference snapshots when it finds differences and to pass the tests. Once Cypress has updated the reference snapshots, the workflow automatically opens a PR to merge the new and/or updated snapshots into the working branch. After this PR is merged, the visual regression tests in the working branch succeed and the branch can be merged into main.

Here is the summarised workflow (also described with screenshots in PR #306):

  1. Push your working branch and open a PR.
  2. If the e2e job of the Lint & Test CI workflow fails, check out the logs.
  3. If the fail is caused by a visual regression (i.e. if a test fails on a cy.matchImageSnapshot() call), download the workflow's artifacts.
  4. Review the snapshot diffs. If the visual regression is unexpected: fix the bug, push it and start from step 2 again. If the visual regression is expected: continue to step 5.
  5. In the PR, post a comment with /approve.
  6. Go to the Actions page and wait for the Approve snapshots workflow to complete.
  7. Go to the newly opened PR titled Update Cypress reference snapshots.
  8. Review the new reference snapshots once more and merge the PR.
  9. Go back to your main PR and wait for the jobs of the Lint & Test workflow to succeed.

Deployment

NPM packages 📚

The src/packages folder contains entry points for the packages published to NPM: @h5web/lib and @h5web/app.

Release process

To release a new version:

  1. Check out main and pull the latest changes.
  2. Make sure your working tree doesn't have uncommitted changes and that the latest commit on main has passed the CI.
  3. Run npm version [ patch | minor | major | <new-version> ]

This command bumps the version number in package.json, commits the change and then tags the commit with the same version number. The postversion script then runs automatically and pushes the new commit and the new tag. This, in turn, triggers the Release workflow on the CI, which builds and publishes the packages to NPM and deploys the Storybook site. The workflow is detailed in issue #358.

Once the Release workflow has completed:

  • Make sure the new package versions are available on NPM and that the live Storybook site still works as expected.
  • Upgrade and test the packages in apps and code sandboxes, as required.
  • Write and publish release notes on GitHub.

Build and test locally

To build the packages, run the following commands:

cd packages
npm install
npm run build

To test a package locally, build the packages then run the following commands:

cd lib/dist
npm link
cd /your/test/app
npm link @h5web/lib

If you see an "invalid hook call" error, you may need to alias the react and react-dom imports to point to your test app's node_modules folder.

Icon set

H5Web uses the Feather icon set. Icons can be imported as React components from react-icons/fi.