Skip to content

Latest commit

 

History

History
353 lines (251 loc) · 13.8 KB

DEVELOPING.md

File metadata and controls

353 lines (251 loc) · 13.8 KB
Raw

Developing

Prerequisites

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

Getting Started

For internal Autodesk folks, make sure to be off the company VPN while setting up and developing.

To get set up, run the following commands:

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

If you see an error about #!/usr/bin/env: No such file or directory, there is likely an issue with conflicting LF and CF/LF line endings. Do a search for /usr/bin/env and convert any found files to use LF line endings.

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.

Use the JSDoc style guide for documentation comments.

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

In general you don't have to worry about maintaining the version number of the package because Semantic Release will automate the process for you. However there may be situations where you are developing a package and don't want its changes to be pushed to other dependent packages (either for local development or via Greenkeeper). In such cases you may want to assign an explicit version and append an "-alpha" tag to indicate that the package is still in development.

Using the sample component 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 and when building dependent packages while in development. In other words, using "-alpha" on your package version will allow you to merge changes into the git development branch without impacting deployment or developers working on their local machines.

In concordance with this, you should make any inter-package dependencies explicit in each package's package.json file. If you wish to include a pre-release package dependency, you will need to specify that pre-release version exactly.

Combined with Semantic Release and Greenkeeper, this ensures that non-breaking (minor and patch versions) updates get cascaded to dependent packages and that breaking updates trigger Greenkeeper notifications.

Creating pre-releases

For controlling release of breaking changes

  • In the commit that contains the breaking changes for a package–and any commit should only contain changes for one package–manually change the package version in package.json to the next major version and append "-alpha". For example, if the package.json looked like this

    {
  "name": "@weave-design/sample-component",
  "version": "1.0.0",
  "description": "",
  "author": "Autodesk Inc.",
  "license": "Apache-2.0"
}

    Manually change the version to 2.0.0-alpha.

  • yarn && yarn build at the project root. You should expect that yarn.lock will be unchanged, indicating that none of your dependent packages pulled in the breaking pre-release changes.

  • Proceed with posting a PR and merging your work into the development branch.

  • When you're ready to release your package, manually remove "-alpha" from the version. For example, if the package.json looked like this

    {
  "name": "@weave-design/sample-component",
  "version": "2.0.0-alpha",
  "description": "",
  "author": "Autodesk Inc.",
  "license": "Apache-2.0"
}

    Manually change the version to 2.0.0.

  • yarn && yarn build at the project root. Expect that yarn.lock will be unchanged, indicating that none of your dependent packages pulled in the breaking, major-version-bump changes. If a dependent package did pull in the breaking change, this might indicate that your package is not explicitly listed as a dependency or that the version compatibility listed in the dependent's package.json is not pinned to restrict updates to only minor and patch levels (e.g. ^1.0.0). Our convention is to list dependencies allowing only minor and patch updates with ^.

  • On your development branch locally, run yarn release:dry-run. Assuming your breaking change commit message follows Angular Git Commit Guidelines, expect that Semantic Release will output something like Create tag @weave-design/sample-component@2.0.0. This indicates that it would bump the version to 2.0.0 and publish it to NPM if this were not a dry run. If you don't see that, double check your previous steps.

  • Proceed with posting a PR and merging your work into the development branch.

  • Your breaking changes under the new major version should not impact other packages without explicitly updating their package.json files.

  • Once your changes make it to master and CI, Semantic Release should properly bump the version to 2.0.0 and publish to NPM.

Other uses

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

For example, @hig/button@1.0.0 can have a pre-release package by changing the version to @weave-design/button@1.1.0-alpha. Subsequent pre-releases can be made by further changing the package version, e.g. @weave-design/button@1.1.0-alpha.2.

A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

Angular Git Commit Guidelines

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 deploy a package

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

  "devDependencies": {
    "@weave-design/scripts": "^x.x.x",
    "@weave-design/semantic-release-config": "^x.x.x",
  },
  "release": {
    "extends": "@weave-design/semantic-release-config"
  },
  "scripts": {
    "release": "weave-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 @weave-design/button@0.1.0, but the current package version is @weave-design/button@1.0.0. Additionally, upgrading to @weave-design/button@1.0.0 isn't an option for the consumer.

We need to patch @weave-design/button@0.1.0, by releasing @weave-design/button@0.1.1 with the fix.

Steps

  1. Checkout a new branch based on the tag for the respective version
git checkout @weave-design/button@0.1.0
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": "@weave-design/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 `@weave-design/button@0.1.1`"
  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