Skip to content

Contribution

This page covers how to propose, implement, and submit changes to CRIEW and the CRIEW wiki. Use it before opening an issue, starting a branch, or sending a pull request.

Before you start

  • Work from the current develop branch.
  • Open pull requests against develop.
  • Keep one logical change per branch, commit, and pull request.
  • English is preferred for public issues and pull requests. Chinese is also acceptable when that is easier.

Open an issue

Prefer the existing GitHub issue forms:

  • Bug report: Use this for regressions, incorrect behavior, crashes, or broken workflow steps.
  • Feature request: Use this for new workflow support, behavior changes, or interface improvements.
  • Documentation issue: Use this for missing, outdated, or unclear docs.

The current templates expect you to:

  • search the existing issues first
  • check the current docs before filing a new issue
  • describe the problem in concrete workflow terms
  • include reproduction steps, environment details, or document locations when they apply

Blank issues are still enabled, but they should carry the same level of detail as the nearest template.

Develop CRIEW

Start a branch

git switch develop
git pull --ff-only
git switch -c <topic-branch>

Follow the repository rules

Read these documents before larger changes:

The required commit rules are:

  • use git commit -s
  • keep the Conventional Commit prefix: feat:, fix:, docs:, refactor:, test:, or chore:
  • keep larger commits focused and include a bullet-point body

The repository hook at .githooks/commit-msg checks the subject format, the Signed-off-by: trailer, and the larger-commit body rule.

Run validation

For CRIEW code changes, run:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
./scripts/check-coverage.sh

If the change affects user-visible behavior, commands, config keys, or workflow rules, update the docs in the same change.

Develop the CRIEW wiki

docs/wiki is a separate Git repository inside the main repository. Treat it as the source of truth for the published wiki site.

Use the local wiki commands from the CRIEW root:

cargo wiki lint
cargo wiki build
cargo wiki serve

Or run:

cargo wiki check

That runs the copy lint and the local site build.

When you change wiki content:

  1. Commit the page changes inside docs/wiki.
  2. Return to the CRIEW root repository.
  3. Commit the updated docs/wiki gitlink there.

GitHub Pages publishes the wiki commit pinned by the main repository. It does not publish the standalone wiki repository's latest HEAD automatically.

Open the pull request

Use the existing pull request template: PULL_REQUEST_TEMPLATE.md

Fill every section that applies:

  • Summary
  • Related Issues
  • What Changed
  • Testing
  • Documentation
  • Checklist
  • Notes For Reviewers

The current template expects:

  • a focused change
  • linked issues when applicable
  • exact local testing commands
  • explicit documentation updates when behavior changed
  • a quick regression check of nearby workflows

Resolve conflicts with rebase

If your pull request conflicts with develop, resolve it with rebase. Do not merge develop into your topic branch just to clear the conflict.

Use this sequence:

git fetch origin
git rebase origin/develop

Then resolve each conflict, stage the fixed files, and continue:

git add <resolved-files>
git rebase --continue
git push --force-with-lease

If the conflict involves the docs/wiki gitlink, finish the wiki-side conflict resolution first, then update the pinned submodule commit in the root repository.

See also