# 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](https://github.com/ChenMiaoi/CRIEW/issues/new?template=bug_report.yml):
Use this for regressions,
incorrect behavior,
crashes,
or broken workflow steps.
- [Feature request](https://github.com/ChenMiaoi/CRIEW/issues/new?template=feature_request.yml):
Use this for new workflow support,
behavior changes,
or interface improvements.
- [Documentation issue](https://github.com/ChenMiaoi/CRIEW/issues/new?template=documentation.yml):
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
```bash
git switch develop
git pull --ff-only
git switch -c <topic-branch>
```
### Follow the repository rules
Read these documents before larger changes:
- [Coding guidelines](https://github.com/ChenMiaoi/CRIEW/blob/develop/docs/development/code-guildline.md)
- [Architecture design](https://github.com/ChenMiaoi/CRIEW/blob/develop/docs/architecture/design.md)
- [Reply format spec](https://github.com/ChenMiaoi/CRIEW/blob/develop/docs/specs/reply-format-spec.md)
- [Configuration example](https://github.com/ChenMiaoi/CRIEW/blob/develop/docs/reference/config.example.toml)
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](https://github.com/ChenMiaoi/CRIEW/blob/develop/.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:
```bash
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:
```bash
cargo wiki lint
cargo wiki build
cargo wiki serve
```
Or run:
```bash
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](https://github.com/ChenMiaoi/CRIEW/blob/develop/.github/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:
```bash
git fetch origin
git rebase origin/develop
```
Then resolve each conflict,
stage the fixed files,
and continue:
```bash
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
- [Development](Development.md)
- [CRIEW wiki home](Home.md)
- [CRIEW repository](https://github.com/ChenMiaoi/CRIEW)