# 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)