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:

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

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 Glossary.

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