Contribution Guidelines
Contribution guidelines define how code and the Rust SME knowledge base stay healthy: PR templates, CODEOWNERS, CI gates, and when to update site/rust/ articles alongside behavior changes.
Recipe
Quick-reference recipe card - copy-paste ready.
# CONTRIBUTING.md essentials
1. Fork/branch from `main`
2. `cargo fmt && cargo clippy -- -D warnings && cargo test`
3. PR description uses template (intent, risk, rollback)
4. Update docs if user-visible or on-call impact
5. SME site article update if fleet pattern changesWhen to reach for this:
- Open source publish
- New engineer asks "how do I contribute?"
- Knowledge base drift from code
- Audit of change control
Working Example
# .github/pull_request_template.md
## Intent
## Risk (migration / unsafe / perf / security)
## Test evidence
## Rollback plan
## Docs
- [ ] rustdoc / README
- [ ] runbook
- [ ] SME site (link PR)# CODEOWNERS
/crates/orders-domain/ @bob @alice
/migrations/ @dba-team @bob
**/unsafe/ @security-rustDeep Dive
Contribution Flow
- Issue or RFC for M/L work.
- Small fixes: issue optional but PR description required.
- CI must pass: test, clippy, audit/deny, migration check.
- Squash merge with conventional commit message optional per team.
SME Site Maintenance
Update site/rust/ when:
- Fleet standard changes (new clippy deny, deploy policy).
- Article referenced in onboarding is wrong.
- New case study from post-mortem approved by guild.
Do not duplicate service-specific secrets or SHAs in SME articles - use placeholders.
External Contributors
good-first-issue labels; MSRV and edition in README; CoC reference.
Gotchas
- CONTRIBUTING exists but CI differs - Fix: Single source; CI badges in README.
- CODEOWNERS stale - Wrong reviewers. Fix: Quarterly audit in retro.
- Docs-only PRs skipped - Knowledge rot. Fix: Same review kindness as code.
- SME site orphan updates - Fix: Link article PR in implementation PR.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Trunk-based all | Mature CI + flags | Learning Rust codebase |
| Fork PR only OSS | External contributors | Internal monorepo |
| Signed commits required | High security | Early startup friction |
FAQs
Who approves SME edits?
Same guild as docs/adr maintainers; link manifest section owners.
Breaking API change process?
Semver bump + changelog + migration guide in PR.
Dependency bot PRs?
Auto-merge patch if CI green; minor needs owner review.
License headers?
Fleet policy in CONTRIBUTING; cargo deny license check.
Embargo security fixes?
Private fork workflow; public SME update after release.
Related
- Code Review Culture - review norms
- Documentation Conventions - where to write
- Unsafe & Dependency Governance - deps
- Git Best Practices - version control
- Governance Best Practices - summary
Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.