Skip to content

Latest commit

 

History

History
162 lines (109 loc) · 6.32 KB

CONTRIBUTING.md

File metadata and controls

162 lines (109 loc) · 6.32 KB
Raw

English | 简体中文

Contributing

Thank you for taking your time to contribute and make this project better! Here are some guidelines to help you get started. Please make sure to take a moment and read through them before submitting your contributions.

Code of Conduct

This project is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to adhere to it.

Open Development

All work happens directly on GitHub. Both core team members and external contributors send pull requests which go through the same review process.

Semantic Versioning

This project follows semantic versioning. We release patch versions for bug fixes or other changes that do not change the behavior of the API, minor versions for new features that are backward-compatible, and major versions for any breaking changes.

Every significant change is documented in the changelog file.

Reporting Issues

We use Github issues for bug reports and feature requests. Before reporting an issue, please make sure you have searched for similar issues as they may have been already answered or being fixed. A new issue should be submitted via issue helper. For bug reporting, please include the minimum code that can be used to reproduce the problem. For feature request, please specify what changes you want and what behavior you expect.

Sending a pull request

This project uses Yarn for package management. Please install Yarn before development.

  1. Fork the repository and create your branch from main. For new feature, please submit your changes directly to the feature branch. Other changes should go against main branch.

  2. Run yarn run init in the repository root.

  3. Run yarn start to start and preview site.

  4. Make changes to the codebase. Please add tests if applicable.

  5. Make sure the test suite passes with yarn test. To watch for specific changes in development, use yarn test:watch TestName (e.g. yarn test:watch Alert).

    Note: Running yarn test on your personal computer may be CPU-burning and even system-crashing. An alternative approach is:

    1. Enable Github Action in your fork
    2. Create a PR within your fork to trigger CI
    3. View the test result in your fork

  6. If you made any props changes (i.e. interface.ts file), DON'T manually update README file under the component. Instead, run yarn docgen to generate the README file automatically.

  7. Commit your changes, adhering to the Commit Guidelines

  8. Open a new pull request, referencing corresponding issues if available.

Commonly used npm scripts

# start and preview site locally
$ yarn dev:site

# checks the javascript code style.
$ yarn eslint

# checks the css code style
$ yarn stylelint

# automatically generate docs
$ yarn docgen

# format code with prettier
$ yarn format

# create a build of the components
$ yarn build

# run the complete test suite
$ yarn test

# start Storybook (no hot reload. To reflect changes, do `yarn build` first)
$ yarn demo

Component demo

The component demo should be syntax complete on its own. It is recommended to use tsx as code block language and install TS in Markdown to get syntax hints in VSCode. The default export in the code block will be the rendered content of the demo.

Commit Guidelines

Commit messages are required to follow the conventional-changelog standard:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit types

The following is a list of commit types:

  • feat: A new feature or functionality
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Code formatting or component style changes
  • refactor: Code changes that neither fixes a bug nor adds a feature.
  • perf: Improve performance.
  • test: Add missing or correct existing tests.
  • chore: Other commits that don’t modify src or test files.

Project Structure

Component directory

components/componentName

├── README.zh-CN.md (Note：Don't edit this file, it's generated by script)
├── README.en-US.md (Note：Don't edit this file, it's generated by script)
├── __template__ （Template used to generate README file）
│   ├── index.en-US.md (EN template)
│   └── index.zh-CN.md （CN template）
├── __changelog__ 
│   ├── index.en-US.md (Note: Don't edit this file manually, it's generated by script on release)
│   └── index.zh-CN.md (Note: Don't edit this file manually, it's generated by script on release)
├── __test__
│   ├── __snapshots__
│   │   └── demo.test.js.snap （Snapshot）
│   ├── demo.test.ts (Snapshot test)
│   └── index.test.ts （Unit test）
├── __demo__ （Demos for each component）
│   ├── basic.md
│   └── advanced.md
├── index.tsx（Component export）
└── style
    └── index.less（Component style）
    └── index.ts (Component style entry)

Template

Template in __template__ directory is used to generate component's README with yarn docgen command. It should follow the structure below:

---
file: index (Inform react-docgen-typescript where to look up interfaces information)
---

`````
Component / Feedback

# Alert

Used to display warning information in a way that attracts attention.
`````

%%Content%% (Placeholder for demos)

## Props

%%Props%% (Placeholder for props)

Please note that if you make changes that will affect README (e.g. props changes), make sure to run yarn docgen to update README of the component.

Changelog

Changelogs in __changelog__ are generated automatically by script on release. Please don't edit the files manually.

License

By contributing your code to the repository, you agree to license your contribution under the MIT license.