Contributor checklist

Single hub for adding or updating a language, config/markup plugins, and shipping a feature change — including which tests to run before opening a PR.

This doc does not replace the deep guides it links to. Use it to pick a path, run the right tests, and paste the commands you ran in your PR.

Setup and clone: CONTRIBUTING.md · Crate map: Code_structure.md

0. Before you code

1. Choose your path

2. Programming languages

Scaffold (all tiers)

1. Add crates/rgctl-lang-{id}/ and register in crates/rgctl-languages/.
2. Update languages.toml (extensions, handler, kinds).
3. Wire workspace Cargo.toml.

Full layout and naming: tier-1-language-support.md §3–4.

Tier 2 / Tier 3 — minimum tests

Promoting Tier 2 → Tier 1: tier-1 §5.

Tier 1 — test matrix (Layers E + F)

Layer definitions (A–F prose, F1–F7 table, honesty limits): tier-1 §2.
Copy-paste PR checklist block: tier-1 §7.

Dashboard gates by language (release mode; external fixture repos — set RGCTL_*_REPO if needed):

Fast dashboard smoke (tiny in-tree fixture): cargo test --test dashboard_bundle.

Parity snapshot: tier-1 §8.

3. Config / markup

Config format plugins

• Code: crates/rgctl-config-formats
• Tier table: languages.md (config formats do not run CFG/PDG)

Run workspace tests touching the format crate; add fixture tests if you change extraction behavior.

Markdown context graph

Deep guide: markdown-context.md. Fixture: tests/fixtures/markdown-context/.

Optional cold profile (large corpus): markdown-context.md § Cold profile.

4. Feature updates

Map what you touched → tests to run. Design detail lives in design/README.md.

Dashboard PR checklist

When changing dashboard/ or crates/rgctl-dashboard/:

• Update dashboard-design.md implementation status
• ./scripts/test-dashboard-golden.sh passes
• Full checklist: dashboard-design § PR checklist

5. Standard test workflow

Run before opening a PR (add path-specific targets from §2, §3, or §4):

cargo fmt --all -- --check

cargo clippy --lib --bins -- -D warnings
cargo clippy -p rgctl-analysis -- -D warnings
cargo clippy -p rgctl-graph -p rgctl-core -- -D warnings

cargo test --workspace --lib --bins --tests

cargo build --release -p rgctl
CARGO_BIN_EXE_rgctl="$PWD/target/release/rgctl" \
  cargo test --test user_guide_scenarios

cargo test --test map_collision_qe
cargo test --test graph_correctness
cargo test --test semantic_search_qe
cargo test --test cross_feature_qe

cargo test --test cli_output
cargo test --release --test subprocess_golden_path
cargo test --release --test all_commands_sanity

cargo test --release --test blast_radius_perf

Optional release-mode dashboard gates: add --release --test dashboard_* targets from §2.

CLI I/O layer reference: cli-io-sanity-qe.md. Workflow mirror: .github/workflows/ci.yml.

6. Documentation & PR

Doc updates

Signed commits and DCO

Every commit in a PR must include DCO sign-off — use -s / --signoff so the commit message contains:

Signed-off-by: Your Name <your.email@example.com>

The sign-off certifies agreement with the Developer Certificate of Origin (DCO).

One-shot:

git commit -s -m "your message"

Verify before push:

git log -1 --format=%B | grep -i '^Signed-off-by:'

Open the PR

1. Branch from main.
2. Fill in .github/PULL_REQUEST_TEMPLATE.md.
3. List exact commands you ran (see §5).
4. Tier 1 language PRs: paste the checklist from tier-1 §7.

7. Decision tree

                    ┌─────────────────┐
                    │  What changed?  │
                    └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         ▼                   ▼                   ▼
   ┌───────────┐      ┌─────────────┐     ┌─────────────┐
   │ Language  │      │ Markup /    │     │ Feature /   │
   │ plugin    │      │ config      │     │ infra       │
   └─────┬─────┘      └──────┬──────┘     └──────┬──────┘
         │                   │                   │
    Tier 1?              Markdown?           See §4 table
    ├─ yes → §2          ├─ yes → §3         + design doc
    │   Tier 1 matrix    │   markdown_*      │
    └─ no → §2           └─ else config      Dashboard?
       Tier 2/3 min          formats              │
                              crate tests     §4 dashboard
                                                checklist
         │                   │                   │
         └───────────────────┴───────────────────┘
                             │
                             ▼
              §5 standard test workflow
                             │
                             ▼
              §6 signed commits + DCO + PR template

See also

• CONTRIBUTING.md — clone, build, test overview
• tier-1-language-support.md — Layer A–F depth
• cli-io-sanity-qe.md — CLI test layers
• dashboard-design.md — WASM export pipeline