Skip to content

Latest commit

 

History

History
213 lines (125 loc) · 8.63 KB

CONTRIBUTING.md

File metadata and controls

213 lines (125 loc) · 8.63 KB
Raw

Contributing Guide

This guide is heavily inspired by antfu/contribute.

Hey there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great and we truly appreciate your time and effort.

Important

Before submitting your contribution, please take a moment and read through the following guidelines.

👨‍💻 Repository Setup

Note

Windows users: see special note below.

This project uses Bun as a runtime as well as a package manager. It's a modern, fast, and lightweight alternative to Node.js and npm. To install Bun, run the following command:

curl -fsSL https://bun.sh/install | bash

Special note for Windows users

This guide assumes you are using a Unix-like environment, since Bun is working on a Windows port. If you are using Windows, you can use WSL or Git Bash.

💡 Commands

bun dev

Start the development environment in watch mode.

bun build

Build the project for production. The result is under dist/.

bun lint

We use Biome for both linting and formatting. It is an ultra-fast, Rust based linter and formatter. It also lints JSON.

You can run bun lint --apply to apply any safe fixes automatically.

We don't use Prettier.

bun test

Note

This is just a placeholder for now. We will add more details later once tests are formally added.

Run the tests. We mostly using Vitest - a replacement of Jest.

You can filter the tests to be run by bun test [match], for example, bun test foo will only run test files that contain foo.

Config options are often under the test field of vitest.config.ts or vite.config.ts.

Vitest runs in watch mode by default, so you can modify the code and see the test result automatically, which is great for test-driven development. To run the test only once, you can do bun test --run.

For some projects, we might have multiple types of tests set up. For example bun test:unit for unit tests, bun test:e2e for end-to-end tests. bun test commonly run them together, you can run them separately as needed.

bun docs

Start the documentation dev server. Use bun docs:build to build the docs for production.

bun run

Print a full list of available scripts.

🙌 The Road to a Great Pull Request

Discuss First

Before you start to work on a feature pull request, it's always better to open a feature request (FR) issue first to discuss with the maintainers whether the feature is desired and the design of those features. This would help save time for both the maintainers and the contributors and help features to be shipped faster.

For typo fixes, it's recommended to batch multiple typo fixes into one pull request to maintain a cleaner commit history.

Commit Conventions

We use Conventional Commits for commit messages, which allows the changelog to be auto-generated based on the commits. Please read the guide through if you aren't familiar with it already.

Note

A full specification can be found in the AngularJS Git Commit Guidelines.

Only perf:, fix:, and feat: will be present in the changelog.

Note that perf:, fix:, and feat: are for actual code changes (that might affect logic). For typo fixes or document changes, use docs: or chore: instead:

  • fix: typo -> docs: fix typo

Pull Request

If you don't know how to send a Pull Request, we recommend reading the guide.

When sending a pull request, make sure your PR's title also follows the Commit Convention.

If your PR fixes or resolves an existing issue, please add the following line in your PR description according to the following example:

Fixes #123

Where the template is:

<keyword> #<issue-number>

Replacing:

  • <keyword> with one of close, closes, closed, fix, fixes, fixed, resolve, resolves, resolved
  • <issue-number>: the issue number you are fixing

This will let GitHub know the issues are linked, and automatically close them once the PR gets merged. Learn more at the guide.

It's ok to have multiple commits in a single PR, you don't need to rebase or force push for your changes as we will use Squash and Merge to squash the commits into one commit when merging.

🧑‍🔧 Maintenance

This section is for maintainers with write access, or if you want to maintain your own forks.

Release

Before you do, please make sure you have lastest git commit from upstream and all CI checks pass.

When ready to publish a new release, we run bun release. It prompts a list for the target version you want to release. After selecting the desired one, it bumps your package.json and commit the changes with git tags, powered by @antfi/bumpp.

There are two kinds of publishing setups, both performed by bun release.

Build Locally

For this type of setup, the building and publishing process is done on your local machine. Make sure you have your local npm logged in before doing that.

In package.json, we usually have:

{
  "scripts": {
    "prepublishOnly": "bun build"
  }
}

So whenever you run npm publish, it will make sure you have the latest change in the distribution.

Build on CI

For complex projects that take long time to build, we might move the building and publishing process to CI. So it doesn't block your local workflow.

They will be triggered by the v prefixed git tag added by bumpp. The action is usually defined under .github/workflows/release.yml

When maintaining your own fork, you might need to see NPM_TOKEN secret to your repository for it to publish the packages.

Changelogs are always generated by GitHub Actions.

📖 References

Lint

We use Biome for both linting and formatting with a few custom rules. It is an ultra-fast, Rust based linter and formatter.

IDE Setup

We recommend using VS Code along with the Biome extension.

With the settings on the right, you can have auto fix and formatting when you save the code you are editing.


VS Code's settings.json

{
  "editor.defaultFormatter": "biomejs.biome",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "quickfix.biome": true
  }
}

No Prettier

Warning

Since ESLint is already configured to format the code, there is no need to duplicate the functionality with Prettier (Why I don't Use Prettier). To format the code, you can run bun lint --apply or refer to the Lint section for IDE Setup.

If you have Prettier installed in your editor, we recommend you disable it when working on the project to avoid conflict. Instead, you may use the Biome VS Code extension.

🗒 Additional Info

In case you are interested in, here are some interesting tools, many of which inspired or created by antfu.