Skip to content

Latest commit

 

History

History
161 lines (90 loc) · 8.46 KB

CONTRIBUTING.md

File metadata and controls

161 lines (90 loc) · 8.46 KB
Raw

Contributing

Hi, thanks for taking an interest in contributing to the UI Kit repository. We welcome any kind of contribution, from reporting issues or idea to submitting pull requests for bug fixes, improvements, new features, etc.

Please take a moment to review this document in order to make the contribution process straightforward and effective for everyone involved.

Core ideas

The UI Kit repository primarily contains UI components that implement commercetools Design System. The following assumptions and criteria are valid:

  • Components are ideally agnostic to any domain-specific functionality or behavior.
  • Components are meant to be easily composed with each other.
  • Components use Design Tokens defined in the Design System.
  • Components are implemented following UX Guidelines.

Repository structure

This repository is managed as a monorepo, meaning it contains multiple (sub)packages located in the packages directory.

packages/
  components/
    buttons/
    ...

Some of the packages are used as "presets" and live in the presets folder. Those simply group other packages together to avoid importing each single one of them, for example inputs, buttons, etc.

Development tools

At commercetools we use the following development tools:

Yarn

We use Yarn workspaces to manage dependencies between multiple packages.

Jest

We use Jest as the main framework for testing. Additionally, we take advantage of the Jest runners to run other tasks such as ESLint.

Prettier

We rely on Prettier to consistently format our code.

TypeScript

We prefer to implement our UI components using TypeScript. This has the benefit of provide packages with type declarations, thus a better developer experience, but also to have the codebase more maintainable and less error-prone.

Storybook

We use Storybook to provide a playground UI to showcase and play around with the UI components.

Preconstruct

We rely on Preconstruct to build the packages.

Commitlint

Commit messages should follow a conventional commit format.

Testing

Different forms of testing occur an different levels to ensure the workings of UI Kit.

Testing behavior

Components in UI Kit are integration tested to ensure they meet requirements over time. For this react-testing-library is used. Using Behavior driven development and Jest you specify your acceptance criteria and write expectations based on the component’s state. There are numerous examples in code for existing components. There are many examples of tests when you search for .spec.js files.

Testing visuals

It is crucial for a Design System to not introduce visual regressions. To achieve this UI Kit performs Visual Regression Testing using Percy. Every component must have a so called visual specification alongside it. This is just a React component conveniently defining all visual states such placeholder being filled, a warning being triggered or a component being in readonly state. An example can be found here. This specification is rendered and sent to Percy via a GitHub Action. Once regressions are detected, they will be reported on a subsequent change and have to be approved by a UI/UX Designer.

Opening an Issue

In general, it's a good idea to open an issue first, no matter if it's a bug report, a new feature, etc. Doing so allows maintainers and other contributors to be aware of the context when an associated pull request is provided. It also gives a chance to provide early feedback and suggestions on what the pull request should focus on and what the expectations, avoiding unnecessary work during a pull request.

Developing a new component

When planning to work on a new feature/component, we strongly recommend to start with an issue, describing the use case, the expected interactions, etc. Ideally, some basic design or sketches should be provided to give a clear idea of how the component looks like.

If possible, wait for other maintainers or contributors to give a thumbs up before starting development, to make sure the requirements are accepted.

Submitting a Pull Request

Good pull requests, such as patches, improvements, and new features, are a fantastic help. They should remain focused in scope and avoid containing unrelated commits.

If possible, please try to provide a related issue first, where the topic is discussed and agreed upon before starting to work on that. This is helpful for both you and the maintainers to be familiar with the changes beforehand.

Getting started

  1. Clone the repository.
  2. Run yarn in the root folder to install the dependencies.

At this point you can start working on the UI components in the packages folder.

Some useful commands to work with the repository:

  • yarn test and yarn test:watch
  • yarn typecheck
  • yarn build
  • yarn lint

Developing locally

When you develop UI components, it's recommended to start Storybook.

yarn start

Adding translations

The UI Kit uses react-intl to define and consume messages. The source/core messages are usually defined in messages.js files, co-located to each component that requires messages.

The translations for the supported languages exist in the /i18n folder. We do not use any automated translation software.

After adding new messages, you need to run yarn extract-intl. This will modify the language files in /i18n by adding empty translations for the message keys.

If you want to modify an existing translation, you will need to manually edit the related files in /i18n.

Adding new icons

To add new icons in the @commercetools-uikit/icons package:

  1. Add the raw SVG file to the packages/components/icons/src/svg folder. Make sure the file name ends with .react.svg.
  2. Run the yarn generate-icons command to generate the React component files. The components are generated using the svgr CLI and the template file in svgr/config.js
  3. Run yarn preconstruct dev to generate the necessary entrypoint folders for the icon.

See packages/components/icons/src/CONTRIBUTING.md for more details.

Adding changesets

commercetools ui-kit uses changesets to do versioning and creating changelogs.

As a contributor you need to add a changeset by running yarn changeset. The command will prompt to select the packages that should be bumped, their associated semver bump types and some markdown which will be inserted into the changelogs.

When opening a Pull Request, a changeset-bot checks that the Pull Request contains a changeset. A changeset is NOT required, as things like documentation or other changes in the repository itself generally don't need a changeset.

Releasing packages

commercetools ui-kit uses changesets to do versioning and publishing a release.

A Changesets release GitHub Action opens a Version Packages Pull Request whenever there are some changesets that have not been released yet.

When the Version Packages Pull Request gets merged, the Changesets release GitHub Action will automatically trigger the release.

Canary releases

On main branch, we automatically publish canary releases from CI to the canary distribution channel, after the build runs successfully.

Canary releases are useful to test early changes that should not be released yet to next or latest. They are automatically triggered and released after a Pull Request merged into main.

Branch-specific canary releases

To release a canary version for a specific branch other than the main branch, follow these steps:

  1. Create a PR with a branch name that starts with the prefix preview/  example: preview/canary-branch
  2. To avoid creating versions every time we push, to trigger a canary version with your change, the commit message has to contain the trigger string [publish_preview] example: git commit -m"chore(xxx): [publish_preview] test with a commit trigger" .

Note that canary releases will not create git tags and version bump commits.