Skip to content

developer-guide.md

Latest commit

 

History

History
108 lines (72 loc) · 4.16 KB

developer-guide.md

File metadata and controls

108 lines (72 loc) · 4.16 KB

Developer Guidelines

Setup for Local Development

Prerequisites

  1. Install asdf if not already installed
  2. Clone this repository
  3. cd into the repository

Set Up Pre-Commit Locally

  • See docs for setup
  • Run bash .git/hooks/pre-commit from repo to execute pre-commit on staged files without commiting

What are pre-commit hooks?

Build and Run Storybook

  • Run yarn to install package dependencies (follow any prompts asdf provides)
  • Run yarn bootstrap to install necessary dependencies.
  • Run yarn llink to set up symlinks
  • Run yarn build to compile all packages
  • Run yarn storybook:<theme> where <theme> is bcgov, button, or your custom theme
  • Storybook will open in a browser

Testing

Unit tests

To run unit tests in all packages, run yarn test:jest

Happo screenshots

To generate happo screenshots locally:

  • create an .env file based on env.example and contact Button Inc. for credentials
  • cd into the desired package and run yarn happo run

Installing packages

To install a new package:

  • in the root directory, yarn add [packageName] -W
  • if you have any trouble with directories or files not being found, re-run the commands from Build and Run Storybook above

To install a new package to a Lerna sub-package

  • in the root directory, lerna add [packageName] [--scope={subPackage}] [--dev] (eg. lerna add typescript --scope=@button-inc/button-theme --dev)
  • see the Lerna documentation

Building, Continous Integration, Deploying, and Publishing

Build

To build, run yarn bootstrap followed by yarn llink followed by yarn build-storybook:<theme> where theme is one of:

  • button
  • bcgov

To test build locally, run npx http-server ./storybook-static after building.

Continuous Integration (CI)

It runs a set of checks in github actions to ensure that new changes meet the code conventions and standards.

Checks

  1. Unit tests
  2. Pre-commit hooks

Continuous Deployment (CD)

It generates build artifacts to deploy/publish a new storybook and NPM package versions.

Publish Packages to NPM Registry

In order to avoid potential side effects using lerna version/publish commands, we deploy packages individually using helper scripts in the scripts directory.

  1. Create a new branch off develop called [issue#]-release-[library] (library is base, button, or bcgov)
  2. Log into the NPM registry. (See Toolkit credentials in 1Password.) 
        npm login
  3. Update the version in the package.json of the target package.
  4. Publish the target package to NPM registry using Make command.
    • In the target directory,
        make publish
    • it copies package.json, LICENSE, and README.md files into lib directory to publish the packages based off lib directory.
  5. If desired, update the version of the other packages that reference the updated package. (This happens automatically when you update the base library.)
    • In the root directory,
        yarn sync-version --name=<package-name>
  6. Merge the release branch into develop.

Storybook

  • On develop merge event, new Storybook static artifacts are deployed to github pages in storybook branch.
  • Build and deploy storybook:
    • yarn build-storybook:button or yarn build-storybook:bcgov
    • yarn deploy-storybook Running yarn deploy-storybook does this:
      1. storybook-deployer allows to generate a default index.html that links to all of the loaded storybooks in packages directory.
      2. As storybook-deployer deploys storybook using PAT in CI environment, we only use storybook-deployer to generate the artifacts, and we force update storybook branch using Deploy Key to have fine-grained controls over permissions.