Skip to content

Latest commit

 

History

History
198 lines (114 loc) · 4.89 KB

CONTRIBUTING.md

File metadata and controls

198 lines (114 loc) · 4.89 KB

Contributing

When contributing to this repository, please read through and get familiarised with the processes of making a change to this package.

If you have further questions please discuss the change you wish to make with the owners of this repository.

Get ready for development

You will need:

  • for npm package: Node 16.14 (or up) and npm 8
  • for Android library: Android Studio and OpenJDK 11

1. Install Node

Use nvm to manage the different Node versions and switch between them.

To install and switch to required version run:

nvm install && nvm use

2. Install local Node dependencies

npm install

3. Install Android Studio

Install via Homebrew (Cask):

brew install --cask android-studio

4. Install OpenJDK

Install via Homebrew:

brew install openjdk@11

Finish by following instructions on console to set the exports.

Make a change

  1. Make sure that tests pass:

    npm run test

  2. Make sure that lint passes:

    npm run lint

  3. Commit according to Conventional Commits. We support these tools:

    • Commitizen, which runs automatically on a pre-commit Git hook thanks to Husky.

    • The VS Code plugin.

  4. When opening a pull request, provide as much details as possible for a reviewer to better understand the change.

  5. Check the change manually locally before you assign reviewers.

  6. When a PR is approved - do not merge until acceptance testing is done, and the change is ready for a release.

Run unit tests locally

You can run unit tests as the CI would with:

npm run test

That runs all specs and generates coverage reports.

If you want watch mode for your changes only, use:

npx jest --watch

You can also filter to a single file if you want, like:

npx jest --watch my-file

Build npm package locally

You can build a package by running:

npm run build:npm

It generates design tokens and themes, their definitions, then concurrently executes multiple steps:

  • generating compressed .css theme files (without source map) for vanilla integration
  • generating ESM compiled .js from .ts files with tsc and tsconfig.json

Build Android library locally

You can build a library by running:

npm run build:android

It generates design values (incl. "night" mode), then builds release and debug AARs with Gradle.

Preview locally

You can preview an example generated of base and theme tokens with:

npm run preview

Publish new version

Only maintainers of this repository are allowed to make releases.

Semantic Versioning 2.0.0 is automatically applied and the changelog is automatically generated.

Simply run this script in the root to cut a new release:

npm run release

Optionally you can mark it as pre-release, e.g. 1.0.0-alpha.0

npm run release -- --prerelease alpha

If you need to override SemVer behavior (not recommended):

npm run release -- --release-as 1.1.0

The last line of the script's log will give you the command you need to execute to push the commit and tag.

Release the latest version (example)

You will need release/* branch push permissions.

In the following example we assume that:

  • the latest version is 1.0.0
  • the version 1.1.0 is being released
# ensure tree is clean - WARNING: will delete pending changes
git reset --hard

# get all latest changes from remote
git fetch --all --prune

# checkout latest 'main'
git checkout main
git pull

# create and checkout release branch
git checkout -b release/1.1.0

# use automated release script
npm run release

# push to trigger 'publish' GitHub Action
git push --follow-tags origin release/1.1.0

Open a release PR to merge the version bump and the changelog back to main branch.

# once merged, checkout merge commit on 'main'
git checkout c6da29b

# move version tag
git tag v1.1.0 -f
git push origin v1.1.0 -f

Release a non-latest minor/patch version (example)

You will need release/* branch push permissions.

In the following example we assume that:

  • the latest version is 2.0.1
  • the version 1.2.1 is being released
  • we'll cherry-pick hotfixes from 2.0.1 onto 1.2.0
# ensure tree is clean - WARNING: will delete pending changes
git reset --hard

# get all latest changes from remote
git fetch --all --prune

# checkout latest available version tag for v1.x.x
git checkout v1.2.0

# create and checkout release branch
git checkout -b release/1.2.x

# cherry-pick required fixes from 'main'
git cherry-pick 64b6be1
# pick appropriate commit hashes and repeat as needed

# use automated release script
npm run release

# push to trigger 'publish' GitHub Action
git push --follow-tags -u origin release/1.2.x

No need to open a PR to merge a non-latest release back to main, nor do tags need to be moved.