Contributing

Contributions of code, tests, documentation, and reviews are welcome. Everyone taking part must follow the repository’s Code of Conduct.

Reporting issues

Before filing, search existing issues to avoid duplicates. When creating a new issue, pick the matching template.

Before you start

Except for small bug fixes, typo corrections, wording tweaks, and simple type fixes that do not change behavior, every contribution should start from a GitHub issue. Propose new features in the Feature Requests discussions and wait for approval from the core maintainers before implementing them. Pull requests without an approved issue may be closed.

For a first contribution, look at issues labeled good first issue or help wanted.

Branches and pull requests

The repository has two long-lived branches:

Branch	Role
`dev`	The integration branch and the target of every ordinary pull request
`main`	The production branch; it only receives a `dev` that has passed the full release gate

Create an independent branch from the latest dev, such as feature/<name>, bugfix/<name>, docs/<name>, refactor/<name>, or chore/<name>.
Make your changes and verify them locally as described in Development Setup and Testing.
Rebase your branch on the latest dev before submitting.
Push the branch and open a pull request against dev. CI runs type checking, lint, tests, and packaging.

Feature and bug-fix branches must not target main directly.

Pre-submit checks

Keep each pull request to one feature or one fix; split larger changes into several related pull requests, and split commits logically so they can be reviewed separately.
Run npm run lint to check the code and npm run format:fix to fix formatting. npm run format only checks and does not write.
Add tests for new features, update existing tests your change affects, and run the relevant tests.
Make sure the branch builds, and remove debugging code and stray log output.

The pull request description should explain what changed, how to test it, and any breaking changes; include screenshots for UI changes.

Commit messages

Use the Conventional Commits format, such as feat:, fix:, or docs:, and reference issues with #<issue-number> where relevant. The repository has no hook that validates commit messages; this is a convention rather than an enforced check.

Changelog and versions

Contributors do not write changelog entries in pull requests. Maintainers handle version numbers and the changelog at release time: the Chinese edition is CHANGELOG.md in the repository root, and the English edition is docs/changelog/CHANGELOG_en.md. When a tagged version is packaged, both changelogs must contain the matching ## [X.Y.Z] heading.

Changing the documentation

This site is a separate Astro Starlight project under docs/ and requires Node.js >=22.12.0:

cd docs
npm install
npm run dev      # local preview served at /
npm run verify   # unit tests, content checks, build, and output checks

You can also run npm run docs, npm run docs:check, and npm run docs:verify from the repository root.

Documentation must be submitted in English and Chinese pairs: English pages go in docs/src/content/docs/, and Chinese pages go in the same path under docs/src/content/docs/zh-cn/.

License

By submitting a pull request, you agree that your contribution is licensed under the project’s Apache 2.0 license.