Contributing
Create a branch from the latest master. External contributors can fork Zxilly/cjv, configure the original repository as upstream, and open a pull request against its master branch:
git fetch upstream
git switch -c fix-windows-path upstream/master
Making changes and validating locally
- Reproduce first — Before fixing a bug, reproduce the failure and locate the package that owns the behavior in the Architecture guide.
- Test through production entry points — Add or update regression tests in the owning package rather than testing private helpers in isolation. See Testing and checks for test locations and commands.
- Note platform coverage — When changing platform-specific behavior (such as Windows file locking, Unix shell profile edits, or OpenHarmony self-signing), mention which platforms you tested locally in your PR description and let CI verify the rest of the matrix.
- Keep translations and docs in sync — Keep Chinese (
src/) and English (en/) documentation changes in the same commit. When adding, moving, or removing a chapter, update bothSUMMARY.mdfiles and add a redirect entry inbook.toml(see Documentation site). Frontend copy inweb/uses Lingui (pnpm i18n:extract) and requires English translations inweb/src/locales/en/messages.po(see Landing page).
Atomic commits and commit messages
Each commit should contain one logical change. Submit unrelated formatting, refactoring, and dependency upgrades separately.
Before committing, inspect the recent git history and follow the repository’s convention:
git log --oneline -20
Commit titles use the Conventional Commits form type(scope): description, where (scope) is optional and description is a concise imperative phrase in English:
fix(component): enforce ownership across file edits
refactor(toolchain): centralize host target associations
docs: simplify project toolchain setup
Pull requests
When opening a pull request, describe:
- The trigger or motivation — What user command, configuration, or edge case triggered the problem.
- The resulting behavior — How
cjvbehaves after your change. - Validation — Which test suites and platforms you ran locally.
- Related issues — Links or
#issuereferences to any related GitHub issues.
After pushing your branch, check the GitHub Actions results, inspect any failures, and push follow-up fixes to the same branch as code review continues.
Update the User Guide whenever a change alters CLI flags, configuration fields, or user-visible behavior. In the Developer Guide, keep Architecture focused on stable module responsibilities and invariants—low-level implementation details belong in code comments and tests.