Contributing

Thank you for contributing to CShip!

Prerequisites

• Rust toolchain (stable)

Checks to run before submitting a PR

CI enforces four checks on every pull request. Run them locally before pushing to avoid failing builds:

# 1. Format — CI runs `cargo fmt --check`; fix formatting first
cargo fmt

# 2. Lint — all Clippy warnings are treated as errors
cargo clippy -- -D warnings

# 3. Tests
cargo test

# 4. Release build
cargo build --release

If any of these fail locally, they will fail in CI. Fix them before opening a PR.

Adding a new module

BMAD (Recommended)

This project is built with BMAD.

1. Install BMAD in this repo. npx bmad-method install
2. Run /bmad-quick-dev with a GitHub issue URL or a description of your change — it guides you from intent through spec, implementation, and review.

Manual (Not recommended)

• Create src/modules/{name}.rs and update src/modules/mod.rs. If the module needs config fields, also add a struct to src/config.rs.
• Module signature must be exactly: pub fn render(ctx: &Context, cfg: &CshipConfig) -> Option<String>
• All config structs go in src/config.rs with #[derive(Debug, Deserialize, Default)] and pub Option<T> fields.
• Absent data → explicit match + tracing::warn! + None. Disabled flag → silent None. (Exception: context_bar renders an empty bar with tracing::debug! when context data is absent — this is intentional UX.)

Updating documentation

Most documentation lives in docs/; CONTRIBUTING.md at the repo root mirrors docs/contributing.md (see the last bullet). Update the relevant files alongside your code change:

• New module or config field — add the config option to docs/configuration.md. If the module has non-obvious UX, add a docs/faq.md entry too.
• Removed module or config field — delete or mark deprecated the corresponding entry in docs/configuration.md.
• Behaviour change — update any affected section in docs/configuration.md or docs/faq.md.
• New showcase or example — add the cship.toml config block to docs/showcase.md and place any screenshot or GIF in docs/examples/.
• This guide — CONTRIBUTING.md (repo root) and docs/contributing.md are kept in sync manually; if you edit either for any reason, update the other to match.

Opening a PR

1. Make sure all four checks above pass.
2. Describe what your change does and why in the PR description.
3. Reference any related issues with Closes #<issue-number>.