Contributing

Contributing

The working agreement, condensed from CONTRIBUTING.md. Project structure and architecture live in the repo's docs/; the engineering rules are in docs/PLANNING.md (§73 is binding).

Related pages: Architecture (the gates and lints referenced below) · Getting-Started (build + first run) · Security (invariants you must not break) · Roadmap (where work is needed).

• Quickstart
• Commit conventions
• Ground rules
• Pull requests
• The gates you must pass
• Where CI runs

Quickstart

git clone https://github.com/aliasfoxkde/OpenCodifier
cd OpenCodifier
just ci          # fmt + clippy + test + doc + deny + scan — must pass before every PR
just coverage    # line coverage report (cargo llvm-cov)

Rust stable, MSRV 1.90, edition 2024. No runtime dependencies beyond Rust — the default build is ML-free and runtime-free.

Commit conventions

Conventional Commits: feat:, fix:, docs:, refactor:, test:, chore: — subject ≤ 50 characters, body wrapped at 72.

Ground rules

1. Deterministic-first. Never add an ML inference path where a deterministic rule, filter, or cached result can decide with sufficient confidence (PLANNING.md §3).
2. No placeholders. No TODO/FIXME/unimplemented stubs land on main; the workspace lints deny clippy::todo and clippy::unimplemented.
3. No unwrap()/expect()/panic! in production paths — return Result. Test modules may re-allow unwrap locally, at module level only.
4. core stays pure. opencodifier-core must not gain dependencies on HTTP, MCP, CLI, Tokio, or any ML runtime.
5. Abstention is a feature. Never force a decision when confidence is insufficient; return an explicit abstain/escalate outcome.
6. Raw probabilities are not confidence. Calibrated confidence requires the calibration layer (Confidence); never surface softmax output as final confidence.
7. Document public APIs. missing_docs is warn + CI-enforced -D warnings: undocumented public items fail the build. New public APIs need rustdoc with at least one example or an invariant note.
8. Tests travel with behavior. Every fix or feature lands with tests that fail without it. Schema changes land with fixtures under fixtures/.

Pull requests

• Scoped to one phase/concern; reference the PLANNING.md phase.
• CI green is the bar: cargo fmt --check, cargo clippy -D warnings, cargo test --workspace, cargo test --doc, cargo deny check.
• Keep claims sourced: a number in docs or the site must exist in the docs of record (Benchmarks).

The gates you must pass

just ci (the pre-push contract, mirrored line-for-line by the pipeline):

Gate	Command	Notes
Format	cargo fmt --all -- --check
Lint	cargo clippy --workspace --all-targets -- -D warnings	clippy all+pedantic; unwrap/expect/panic/todo/unimplemented/dbg/print denied
Tests	cargo test --workspace	+ the feature lane cargo test -p opencodifier-model --features llamacpp,tokenizers
Docs	cargo test --doc and RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps	doc warnings fail the build
Supply chain	cargo deny check, cargo audit	licenses/advisories/bans/sources
Pattern scan	aegis --format json scan --file . --baseline .aegis/baseline.json	0 new findings; regenerate the baseline in the same commit as any line-shifting edit (Security)
Coverage	cargo llvm-cov --workspace --lcov	floor 97.5 % on the lcov DA basis, measured in-image

Two boundary lanes are not part of just ci — run them when the boundary itself changes:

• just check-wasm — host tests, the wasm32 compile, a wasm-pack --target nodejs build, and a Node smoke test over the real artifact (Node and wasm-pack are not CI dependencies).
• just check-macjev — the renderer/prep byte-parity lane.

Where CI runs

GitForge is the CI/CD platform of record (.gitforge.yml); GitHub Actions is a mirror, and a red GitHub run is not a code-failure signal. All lanes run on the runner-local opencodifier-ci-rust image with zero runtime tool installs. The e2e lane additionally builds the release binary and drives serve + MCP over the real wire.

Branching: main is ruleset-protected — no direct pushes, no force pushes, no history rewrites of pushed commits; fix forward. Feature branches are one topic each (site work uses site/<topic>).

License

By contributing you agree your work is released under the repository's Apache-2.0 license.