Storybook Dev Server Initialization

Install dependencies with a simple yarn command.

yarn dev runs the command storybook dev -p 6006 which should boot the dev server and open the local host in a browser window.

Import Issues

When you first set this up, you might run into import issues due to Yarn 4. In order to resolve these, you need to run yarn dlx @yarnpkg/sdks vscode (assuming you are on VSCode). more information available here (https://stackoverflow.com/questions/54954337/is-it-possible-to-use-yarn-pnp-with-typescript-vscode)

Additional Scripts

Run the below like yarn <my command>

"build": "storybook build",
"test-storybook": "test-storybook",
"prepare": "husky install"

Commit Hygiene

This repository follows a slightly modified version of the ESLint Commit Message Format. This repository uses the PR title to configure the contents of the commit message of the squashed commit associated with the PR: In general, a PR should use the following structure:

Title

The title should have the following format: <type>(<optional ticket id>): <short summary>

The <type> should be Fix, Update, New, or Breaking for controlling releases.

If the PR need not be associated with a new release, choose any other <type> from the ESLint commit convention tags, such as Docs (documentation), Build (build process), Upgrade (dependency upgrade), or Chore (non-user-facing tasks).

Examples:

• Update: button color adjustment
• New(SNC-222): add dark mode

If your PR title does not follow these commit conventions, merging will be blocked.

See below for more information on how commit structure affects releases.

Releasing

This repository uses Semantic Release to control versioning and releases. Semantic Release's prime purpose is to remove developers from the version numbering process, and this repository embraces that philosophy.

Automatic Releases

Two things primarily determine how a new release is versioned:

1. The commit history leading up to the commit being released (to determine the base version from which to bump)
2. The message of the commit being released (to determine the version incrementation amount)

To release a new version as part of a pull request, use a semantic commit message (prefixes like Fix, Update, New, or Breaking) in the title of your pull request. This repo uses a slightly modified version of the ESLint conventional changelog to describe commit conventions.

• Fix or Update: Initiate a patch release
• New: Initiate a minor release
• Breaking: Initiate a major release

If your PR title does not follow these commit conventions, merging will be blocked.

Under the hood, Semantic Release controls the npm release process entirely by way of managed Git tags. Updating the package.json version number is unnecessary and discouraged.

Releasing a Non-Latest Version

To release a patch version on a previous major version:

• Checkout a new branch off the old version you'd like to release from: git checkout -b <branch-name> <tag-name> (e.g. git checkout -b ethan/patch-fix v2.0.2)
• Commit as normally, using the PR Title conventions outlined above
• Semantic Release will take care of the versioning

Tracking Releases

If you want to view the latest version of the Design System, you have a few options:

• From this repository, run yarn latest-release
• From outside this repository, run npm dist-tags ls @indico-data/design-system

If you want to see all releases:

• From this repository, run yarn all-releases
• From outside this repository, run npm view @indico-data/design-system versions
• View the git tags at https://github.com/IndicoDataSolutions/permafrost for specific information about each release
• Consult the npm registry at https://www.npmjs.com/package/@indico-data/design-system

Do NOT use the version attribute of package.json to track or initiate releases because:

• Semantic Release does not rely on this attribute to trigger releases: https://semantic-release.gitbook.io/semantic-release/support/faq
• Adding an additional commit to update the version number adds complexity to the CI process and clutters commit history

Manual Releases

Do not manually release Permafrost to npm, as it may cause issues with the Semantic Release pipeline.

Theming Addon Documentation

Addon - Themes

https://github.com/storybookjs/storybook/tree/next/code/addons/themes

CSS Data ATTR

https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#writing-a-custom-decorator