# Contribution guidelines
First off, thank you for considering contributing to cjkfmt.
If your contribution is not straightforward, please first discuss the change you
wish to make by creating a new issue before making the change.
## Reporting issues
Before reporting an issue on the
[issue tracker](https://github.com/sgryjp/cjkfmt/issues),
please check that it has not already been reported by searching for some related
keywords.
## Pull requests
Try to do one pull request per change.
### Updating the changelog
For each change that affects users, add a changelog entry to the **Unreleased**
section of the [CHANGELOG](https://github.com/sgryjp/cjkfmt/blob/main/CHANGELOG.md).
Changes that do not affect users do not need an entry.
Place each entry under the appropriate subsection, based on the change type,
as defined by [Keep a changelog](https://keepachangelog.com/en/1.0.0/):
- `Added` for new features.
- `Changed` for changes in existing functionality.
- `Deprecated` for soon-to-be removed features.
- `Removed` for now removed features.
- `Fixed` for any bug fixes.
- `Security` in case of vulnerabilities.
If the required subsection does not exist yet under **Unreleased**, create it!
## Developing
### Set up
This is no different than other Rust projects.
```shell
git clone https://github.com/sgryjp/cjkfmt
cd cjkfmt
cargo test
```
#### Setting up lefthook
This project uses [lefthook](https://github.com/evilmartians/lefthook) to enforce linting and
formatting standards. To set it up:
1. Install lefthook (if you haven't already):
```shell
# Using Homebrew (macOS)
brew install lefthook
# Using scoop (Windows)
scoop install lefthook
# Other installation methods are available at https://github.com/evilmartians/lefthook
```
2. Initialize lefthook in the repository:
```shell
lefthook install
```
This will set up Git hooks that will run linters and formatters automatically on commit and push
operations.
Markdown files are linted on commit using [markdownlint-cli2] (via `npx`),
following the rules in [`.markdownlint.yml`](./.markdownlint.yml).
Make sure you have [Node.js](https://nodejs.org/) installed so `npx` is available.
### Useful Commands
- Build and run release version:
```shell
cargo build --release && cargo run --release
```
- Run Clippy:
```shell
cargo clippy --all-targets --all-features
```
- Run all tests:
```shell
cargo test --all-features
```
- Check to see if there are code formatting issues
```shell
cargo fmt --all -- --check
```
- Format the code in the project
```shell
cargo fmt --all
```
- Check Markdown files for style issues
```shell
npx --yes markdownlint-cli2 "**/*.md"
```
### Document-based check tests
Each check test case lives in its own directory under `test_cases/check/`:
```text
test_cases/check/<case>/
├── case.json
└── input.md
```
`case.json` must contain `input_file`, `config`, and `diagnostics`. Use an empty array
when the case expects no diagnostics. The optional `language` field accepts `markdown`
or `json`; it overrides language detection from the input file extension. Without it,
`.md`/`.markdown` and `.json` select their matching Language. An unsupported or missing
extension is an error.
Diagnostic positions use zero-based line numbers and zero-based UTF-16 code-unit columns.
The end position is exclusive. Keep the expected diagnostics in their actual order.
Input files are read as UTF-8 without trimming whitespace or changing line endings. Do
not add or remove a final newline unless it is part of the test input. Fixture-specific
editor and Git settings preserve these bytes. Markdown fixture files are excluded from
Markdown lint because they may intentionally contain lint violations.
To add a case, create its directory, add `case.json`, and save the input document as a
separate file referenced by `input_file`. Keep that file within the case directory. Run
all check and unit tests with:
```shell
cargo test --all-features
```
[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2