Skip to content

Latest commit

 

History

History
297 lines (207 loc) · 8.87 KB

DEVELOPING.md

File metadata and controls

297 lines (207 loc) · 8.87 KB

Developing

Prerequisites

The following dependencies must be available to be begin project development.

Getting Started

To get set up, run the following commands:

git clone https://github.com/Autodesk/hig
cd hig
yarn
yarn build

Project structure

Monorepo

This project is structured as a monorepo, with each package residing within its own directory.

The monorepo uses Yarn workspaces and Lerna to manage the interdependencies between packages.

Private packages

Private packages are used to organize development tools and dependencies. For example, the @hig/scripts package contains the build script that's used to build every component package.

Code style

We use ESLint and Prettier to ensure consistency throughout the source code. Please view our ESLint configuration for details on style rules.

Testing

Unit testing

Jest along with Enzyme is used to run our unit testing suite. While we aim for the highest possible code coverage, every component should be covered with a snapshot test at the very least.

How it works

Unit tests reside within module specifications (moduleName.test.js), which are placed next to their respective modules. Jest runs all of the project's unit tests together, and evaluates code coverage on the project as a whole.

How to run manually

yarn test

How to update snapshots

yarn test -u

Visual regression testing

To ensure that changes do not break the visual presentation of components, we run a suite of visual regression tests via Gemini.

How it works

The tests are run upon a Storybook developed specifically for automated testing. Screenshots of each test are stored within the repository similar to unit test snapshots.

How to run manually

cd packages/storybook
yarn gemini-update  # Update snapshots
yarn gemini         # Check components against committed snapshots

Git commits

Commit messages should adhere to the Angular Git Commit Guidelines.

Package versioning

Package versioning is automated via Semantic Release and determined by commit messages. Commit messages should adhere to Angular Git Commit Guidelines.

New package version

Using the example package documentation as a reference, create a new package with the version 1.0.0-alpha.

Per Semantic Versioning 2.0.0, the "-alpha" portion of the version labels the package as pre-release. Packages labeled as pre-release are ignored during deployment.

Creating pre-releases

Packages that have already been published can have pre-releases as well.

For example, @hig/[email protected] can have a pre-release package by changing the version to @hig/[email protected]. Subsequent pre-releases can be made by further changing the package version, e.g. @hig/[email protected].

Deployment

Storybook

Storybook is deployed when changes are merged into the master branch. Storybook Staging is deployed when changes are merged into the development branch.

Packages

Packages are published via Semantic Release.

New packages

New packages should be labeled as pre-release and are ignored during deployment. For the deployment workflow to recognize them, the pre-release version must be changed to a stable version. For example, 1.0.0-alpha should be changed to 1.0.0.

Pre-releases

Packages labeled as pre-release are ignored during deployment, and must be published manually via the appropriate CLI tools.

How to deploy

  1. Create a pull request (PR) to merge development into master.
    • Begin the PR title with Release: for consistency.
    • Add the release issue label for discovery.
  2. Wait for the PR to receive approval and all automation to finish.
  3. Merge the PR with a merge commit
    • Merging with a merge commit ensures there's no loss of commit information.

Semantic Release will then:

  1. Create new Git tags
  2. Create/update changelogs
  3. Publish new package versions to NPM
  4. Update the master branch
  5. Create GitHub releases
  6. Merge all changes into the development branch

Configuring Semantic Release to deply a package

A package must have the following properties defined in its package.json file in order to be published by Semantic Release

  "devDependencies": {
    "@hig/scripts": "^x.x.x",
    "@hig/semantic-release-config": "^x.x.x",
  },
  "release": {
    "extends": "@hig/semantic-release-config"
  },
  "scripts": {
    "release": "hig-scripts-release"
  },

Documentation

Updating table of contents

Every table of contents is generated using doctoc.

To update each document's table of contents run:

yarn docs

How to fix an old release

Scenario: a consumer reports a critical bug for @hig/[email protected], but the current package version is @hig/[email protected]. Additionally, upgrading to @hig/[email protected] isn't an option for the consumer.

We need to patch @hig/[email protected], by releasing @hig/[email protected] with the fix.

Steps

  1. Checkout a new branch based on the tag for the respective version
git checkout @hig/[email protected]
git checkout -b fix/button
  1. Update the working directory
yarn install
yarn run build
  1. Make the necessary changes for the fix
  2. Commit changes following the Git commit guidelines
  3. Bump the package version

packages/button/package.json

{
  "name": "@hig/button",
- "version": "0.1.0",
+ "version": "0.1.1"
}
  1. Update the CHANGELOG.md
    • Adhere to the existing format
  2. Commit changes
git add packages/button/package.json
git add packages/button/CHANGELOG.md
git commit -m "chore(release): bump version to `@hig/[email protected]`"
  1. Merge development branch and resolve conflicts
git merge development --no-ff
  1. Follow standard pull request procedure
    • Wait for CI to successfully complete
    • Wait for pull request approval
    • Merge PR with merge commit
  2. Publish package
cd ./packages/button
npm publish
  1. Create a Git tag and release entry via GitHub
    • The tag should point to the commit with the chore(release) message