DocsContribution

How to contribute

Prerequisites

  • Node.js v20
  • pnpm v8 to manage packages and dependencies
  • storybook for rapid UI component development and testing
  • changeset for changes documentation, changelog generation, and release management.

Scripts

Root directory

  • pnpm install: bootstraps the entire project, symlinks all dependencies for cross-component development and builds all components.
  • pnpm build: run build for all component packages.
  • pnpm release: publish changed packages.
  • pnpm storybook: starts storybook server and loads stories in files that end with .stories.tsx.
  • pnpm gen:embedded-story: generate embedded story for documentation.

packages/uikit

  • pnpm build:icon: generate react components from all svg files in packages/uikit/src/icons/raw and save to packages/uikit/src/icons/react.

packages/documentation

  • pnpm dev: start the local dev server for documentation.
  • pnpm build: run lint and build the documentation.

Developing

Run pnpm i && pnpm build && pnpm storybook to start the project in development mode.

Your working area is uikit and stories. Once you finish your coding in the uikit, please write some stories for testing.

Icons

To add new icons, you can put the svg file to packages/uikit/src/icons/raw folder then run pnpm build:icon under packages/uikit directory to generate the react component.

It will also update the import entry in packages/uikit/src/icons/index.ts. Note that you should always use the script to update it and avoid manually modifing the import entry file.

The icon script will

  • scan all the svg icon in packages/uikit/src/icons/raw folder
  • Rename all the svg file to PasCal case (or upper camel case)
  • Use svgr to generate correspondent react jsx code to packages/uikit/src/icons/react folder
  • Use a custom code template to support other props such as size
  • By default, it will skip if there are already a jsx file with same name, unless you pass a --force flag
💡

Note that the svg file should be aligned with our design standard. It should be 24x24 by default and no hard-coded color or stroke in all attributes otherwise we wouldn’t be able to customize it via css.

Developing documentation

After installing dependencies with pnpm install, cd to packages/documentation, create a .env file with following content:

NEXT_PUBLIC_STORYBOOK_HOST=https://tidbcloud-uikit-story.netlify.app/

# if you want to reference your local storybook, set to
# NEXT_PUBLIC_STORYBOOK_HOST=http://localhost:6006

then run pnpm dev to start the local dev server for documentation.

Making a pull request

Commit Convention

Before you create a Pull Request, please check whether your commits comply with the commit conventions used in this repository. When you create a commit, you should follow the convention category(scope or module): message in your commit message while using one of the following categories:

  • feat/feature: all changes that introduce completely new code or new features
    • For example: feat(uikit/components), feat(uikit/hooks)
  • fix: changes that fix a bug (ideally you will additionally reference an issue if present)
  • refactor: any code related change that is not a fix nor a feature
  • chore: all changes to the repository that do not fit into any of the above categories

Pull Request

Once you’ve committed your message. You can do your PR

  1. Make a changeset
pnpm changeset
  1. Follow the changeset interactive prompts, commit your change
git commit -m 'feat(uikit): your message'
  1. Push the changes, request a PR. Waiting for the review and merged with the master

Release Process

Each pull request that includes user-facing changes or API modifications should include a changeset:

  1. Generate a changeset file:
pnpm changeset

  1. Follow the interactive prompts to:

    • Select the packages that have changed
    • Choose the type of change (major/minor/patch)

  2. The changeset summary will be generated automatically from commit history. Commit the generated .changeset/*.md file along with your changes.

The changeset bot will also check your PR and comment if a changeset is missing in your PR. You can also use the link provided by the bot to create a changeset directly through GitHub’s UI.

Then the release process will be handled automatically:

  • When PRs with changesets are merged, a Release PR that will bump the version and update the changelog will be created by the changeset bot.
  • Once the Release PR is approved and merged, packages will be published to the registry automatically.

Prerelease

For beta versions, you can use the following command to enter prerelease mode, then follow the instructions just like the normal release process to include a changeset in every PR:

npx changeset pre enter beta

After you are done with your beta changes, you can exit the prerelease mode by running:

npx changeset pre exit

Then run changeset version to version packages with normal versions.

UsageGetting Started