Hey there! We are really excited that you are interested in contributing. This is a general contribution guide for most of my projects. Before submitting your contribution, please make sure to take a moment and read through the following guide:

We use pnpm for most of the projects, we highly recommend you install ni so you don't need to worry about the package manager when switching across different projects.

We will use ni's commands in the following code snippets. If you are not using it, you can do the conversion yourself: ni = pnpm install, nr = pnpm run.

To set the repository up:

Start the development environment.

If it's a Node.js package, it will start the build process in watch mode.

If it's a frontend project, it usually starts the dev server. You can then develop and see the changes in real time.

If it's a Node.js package, it starts a dev server for the playground. The code is usually under playground/.

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

We use ESLint for both linting and formatting. It also lints for JSON, YAML and Markdown files if exists.

You can run nr lint --fix to let ESLint formats and lints the code.

Learn more about the ESLint Setup.

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

You can filter the tests to be run by nr test [match], for example, nr 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 nr test --run.

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

If the project contains documentation, you can run nr docs to start the documentation dev server. Use nr docs:build to build the docs for production.

For more, you can run bare nr, which will prompt a list of all available scripts.

Before you start to work on a feature pull request, it's always better to open a feature request 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.

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.

Only fix: and feat: will be presented in the changelog.

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

• fix: typo -> docs: fix typo

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 (replace 123 with a real issue number):

fix #123

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.

To enable it, run

corepack enable

You only need to do it once after Node.js is installed.

{
  "packageManager": "[email protected]"
}

We use ESLint for both linting and formatting with @luxass/eslint-config.

// .vscode/settings.json
{
  // will ensure that eslint can use the experimental flat config
  "eslint.experimental.useFlatConfig": true,

  // disable the default formatter
  "prettier.enable": false,
  "editor.formatOnSave": false,

  // auto fix on save
  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit",
    "source.organizeImports": "never"
  },
  
  // silent the stylistic rules in you IDE, but still auto fix them
  "eslint.rules.customizations": [
    { "rule": "style/*", "severity": "off" },
    { "rule": "*-indent", "severity": "off" },
    { "rule": "*-spacing", "severity": "off" },
    { "rule": "*-spaces", "severity": "off" },
    { "rule": "*-order", "severity": "off" },
    { "rule": "*-dangle", "severity": "off" },
    { "rule": "*-newline", "severity": "off" },
    { "rule": "*quotes", "severity": "off" },
    { "rule": "*semi", "severity": "off" }
  ],

  // The following is optional.
  // It's better to put under project setting `.vscode/settings.json`
  // to avoid conflicts with working with different eslint configs
  // that does not support all formats.
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue",
    "html",
    "markdown",
    "json",
    "jsonc",
    "yaml"
  ]
}

I would like to thank antfu for his contribution guide which I used as a template for this one.