# Contributing

English is canonical for source code, API names, docstrings, issues, pull requests, and source documentation. User-facing documentation and diagnostics ship in English and Japanese.

## Set up a checkout

Contributor commands require uv 0.12.1 and the stable Rust toolchain:

```bash
git clone https://github.com/Nue-Japan/cognoxium.git
cd cognoxium
uv sync --extra dev
uv run maturin develop
```

The repository commits both `Cargo.lock` and `uv.lock`. Update either lockfile intentionally, review its diff, and run `uv lock --check` plus Cargo's `--locked` checks before opening a pull request.

## Run checks

```bash
uv run pytest
uv run ruff check python tests scripts
uv run mypy
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace --locked
uv run sphinx-build -W -b doctest docs docs/_build/doctest
uv run sphinx-build -W -b html docs docs/_build/en/latest
uv run sphinx-build -W -b html -D language=ja docs docs/_build/ja/latest
```

Public behavior requires tests, English API documentation, and a Japanese translation. Every user-facing code example should be deterministic and executable. New diagnostic codes must be unique and must never be reused for another meaning.

## Documentation changes

Changes to English Markdown require regenerated gettext templates and updated Japanese PO entries. A stable release cannot contain empty or fuzzy user-facing Japanese translations.

Prefer small examples that include expected output. Keep API identifiers and structured values in English, while translating Japanese explanatory prose naturally according to {doc}`glossary`.

See the repository `CONTRIBUTING.md` for the pull-request checklist. Documentation improvements are welcome even when they do not change code.