Welcome to The Royal Opera House Front End Design System, `@royaloperahouse/harmonic`
Welcome to The Royal Opera House Front End Design System, @royaloperahouse/harmonic
This package is a library of UI components intended to be used in the ROH website.
It uses React, TypeScript, TSDX and Storybook.
The NPM packages are published at Royal Opera House - Harmonic
The Storybook for the latest version of the library is hosted at [Storybook - Harmonic] TODO: S3 deployment
* Make sure the required package dependencies are installed using yarn install
* If this is the first time you are working on Harmonic, make sure to run yarn build to build all the modules.
* To deploy the storybook publicly you will need credentials for the parent 'Royal Opera House' AWS account in your ~/.aws/credentials file.
* The deploy script expects these to be called [parent].
* You can find these values at:
AWS 'Your Applications' page -> 'Royal Opera House' -> 'Developer Access' -> 'Command line or programmatic access'
* To deploy a preview for demo / QA you will need:
* A Chromatic account with a Developer role in the roh-ml project in Chromatic
* Mari Lovell is the current owner of this project, you can contact her to invite you
* The CHROMATIC_PROJECT_TOKEN -- find this in 1Password or ask the project owner.
* To enable publishing to the NPM package:
* Create account / log in to NPM
* Ask a colleague with admin rights to be added as a contributer
* Generate your own ROH NPM_TOKEN (store this token in 1Password)
* Set up Two-Factor Authentication for NPM, as you will be prompted by the publishing script
We are not yet using semantic versioning.
When proposing changes to the Harmonic library, increment the patch version (the last number) by one, only in the changelog (alternatively, leave the version in the changelog as TBC) along with a note about your changes.
Only increment the version in the package.json for releasing snapshots.
Once your changes are merged to the main branch and released in a new version, the release manager will be responsible for incrementing that release version.
> NOTE: The following may apply once the Harmonic project is out of Alpha, but is subject to change before then.
We use Semantic Versioning for Harmonic.
Given a version number MAJOR.MINOR.PATCH, increment the:
* MAJOR version when you make incompatible library changes
* MINOR version when you add functionality in a backwards compatible manner
* PATCH version when you make backwards compatible bug fixes
When you create a new release always update the CHANGELOG and package.json
Increment your version from the latest stable version on Royal Opera House - Harmonic
You can quickly build and serve the contents of /storybook-static from your local machine, for development and manual testing. To do this run:
``bash`
yarn storybook
By default the storybook will be accessible at
[http://localhost:6006/]()
The server will hot-reload on most changes.
You can deploy a release candidate, or work-in-progress to Chromatic for showcase or QA.
NOTE: you will need the CHROMATIC_PROJECT_TOKEN and to be invited as a contributor to the Harmonic project in Chromatic, as described in Prerequisites above.
Either set the token as a shell variable or use a .env file in the harmonic root directory containing the token, as so:
`
CHROMATIC_PROJECT_TOKEN=tokengoeshere
Run:
`
CHROMATIC_PROJECT_TOKEN=tokengoeshere yarn deploy-storybook-dev
to build and deploy the storybook from your repo to Chromatic.
You will find the address of your deployed storybook in the console output, looking something like this:
→ View your Storybook at https://randomHexString-randomAlphabeticalString.chromatic.com
to S3 as a static site, which is permanently accessible at [WIP] TODO: S3 deploymentNOTE: To do this you will need the correct
AWS credentials set up, as described in Prerequisites above.First build the storybook using:
`
yarn build-storybook
then run:
bash
yarn deploy-storybook
`> IMPORTANT: This URL is intended to showcase the latest stable version of Harmonic, it should be kept up to date with the
Harmonic branch and should only be used for release versions. If you want to deploy a development version follow the steps above under To deploy a preview version remotely.
Releasing a New Package Version
---This is the procedure for releasing a new Harmonic NPM package.
There are two types of package:
A snapshot can be published to use a development version of the Harmonic library in our frontend staging environments, to perform integrated, manual testing.
A stable package is published for use in production.
NOTE: You will need the
NPM_TOKEN, as described in 'Prerequisites' above.$3
> IMPORTANT: Make sure you always publish your snapshots from
development after merging in your feature branch.For snapshots,
RELEASE_VERSION should be the same as the latest stable version of the Harmonic Library, as found in npm Harmonic - Versions, followed by an unused lowercase letter.For example, if the latest stable release was 1.42.0, and the last snapshot published to NPM was 1.42.0-w, you would use RELEASE_VERSION
1.42.0-xTo publish a snapshot use:
bash
NPM_ROH_TOKEN={NPM_TOKEN} RELEASE_VERSION={RELEASE_VERSION} yarn publish-snapshot
`The version published to NPM will be named, e.g.
, use this to install the snapshot package in the frontend repos.$3
> IMPORTANT: Make sure you always publish your stable packages from
main after merging in your feature branch.For stable releases, increment your version from the latest stable version found on npm Harmonic - Versions, following the rules described in Versioning above, and use this as
RELEASE_VERSION. (Make sure it matches the version in your package.json and CHANGELOG.md!)To publish a stable package use:
`bash
NPM_ROH_TOKEN={NPM_TOKEN} RELEASE_VERSION={RELEASE_VERSION} yarn publish-release
`
Using the Package
---The package is deployed to NPM, and can be installed using yarn or npm:
bash
npm i --save @royaloperahouse/harmonic
`
bash
yarn add @royaloperahouse/harmonic
`
Testing
---To Lint the package use:
bash
yarn lint
Use the --fix option to perform automatic fixes
`To run the unit tests (using Jest) use:
bash
yarn testUse the -u option to update snapshots if needed
Run
yarn test:watch to re-run tests on changes
`To run and and store the unit tests for display in storybook use:
bash
yarn test-storybook
Use the -u option to update snapshots if needed
`
Development Process
---$3
The Harmonic project lives in the repository*
* When working on Harmonic, treat the harmonic directory as your root
* The Harmonic development branch is for QA
* The Harmonic main branch is currently for stable releases
* All work should be done on a correctly named feature branch of the format: issueType/ticketNumber-short-description-of-feature, e.g. feature/RD-12345-add-example-component
* Always create your feature branch FROM, and submit pull requests TO, the main branch
* For QA / UAT of a Harmonic component in isolation: following review you should deploy a preview version to Chromatic straight from your feature branch _without_ merging to development
* For releasing an NPM snapshot: merge your feature branch into the development branch and publish the NPM snapshot from there$3
#### Before review:
* Git pull the latest version of Harmonic from
* Checkout a new, correctly-named feature branch from
* Do your work on this feature branch
* Run:
* Run:
* Commit your changes
* Create a pull request from your feature branch to
* Add the appropriate reviewers#### Before QA / UAT:
After your PR is approved, you have two options:
i. For QA of a component in isolation:
Follow the steps above in Deploying the Storybook -> 2. Deploying a preview version remotely*
* Share the generated Chromatic URL with the appropriate people for QA / UAT
ii. For integrated testing of a component in the frontend staging environments:
* Check out the
branch
* Merge your work in to development
Follow the steps above under Publishing a New Package Version -> 1. To release a snapshot version*
* Git push the updated branch to remote
* Finally, in the frontend repo:1. Update the
package.json to reference the new snapshot version
2. Run: yarn install
3. Deploy the frontend to a staging environment#### When ready for production:
* Return to your Harmonic feature branch
Update the HArmonic version in
, incrementing from the last stable release, found in npm Harmonic - Versions, and following the rules described in the Versioning* section
* Update CHANGELOG.md, adding the new version number and a short description of your changes
* Run: yarn lint --fix
* Run:
* Run:
* Run:
* Git commit, push, and update your PR for final approval
* Merge your approved PR to
Follow the steps in Publishing a New Package Version -> 2. To release a stable version* to publish the NPM package
Finally, follow the steps in Deploying The Storybook -> 3. To deploy a release version*, to update the public Harmonic Storybook pageOnce you have successfully published a new release version, you can open a ticket to update to this version in any of the frontend repos.
Notes
---
$3
This folder contains all the HTML / JS required to deploy the Storybook as a static site. It's autogenerated whenever the Storybook is built and therefore will show up a lot of merge conflicts when you merge other branches into your feature branch. It is best to leave generating the storybook until the later part of your workflow, but in case you run into conflicts earlier, it's ok to just delete the folder and regenerate using:
bash
yarn build-storybook
`For the same reason changes to this folder will cause a lot of big diffs, when looking at a PR, but can mostly be skimmed over unless something looks unusual.
---
$3
There is an example implementation in the example folder. Alternatively there are also integration examples in storybook. Make sure to keep these updated so as to showcase the current components available.
---
$3
Calculate the real cost of your library using size-limit with
and visualize it with yarn analyze`.