Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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

  1. Reproduce first — Before fixing a bug, reproduce the failure and locate the package that owns the behavior in the Architecture guide.
  2. 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.
  3. 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.
  4. 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 both SUMMARY.md files and add a redirect entry in book.toml (see Documentation site). Frontend copy in web/ uses Lingui (pnpm i18n:extract) and requires English translations in web/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 cjv behaves after your change.
  • Validation — Which test suites and platforms you ran locally.
  • Related issues — Links or #issue references 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.