Skip to content

docs(architecture): add dependency_policy.md and CONTRIBUTING.md cross-link (Phase 8c, refs #195)#294

Merged
githubrobbi merged 1 commit into
mainfrom
docs/dependency-policy-phase-8c
May 19, 2026
Merged

docs(architecture): add dependency_policy.md and CONTRIBUTING.md cross-link (Phase 8c, refs #195)#294
githubrobbi merged 1 commit into
mainfrom
docs/dependency-policy-phase-8c

Conversation

@githubrobbi
Copy link
Copy Markdown
Collaborator

Summary

Phase 8c — fourth code-quality policy doc. Mirrors panic_policy.md (Phase 5e), allocation_policy.md (Phase 6f), and trait_policy.md (Phase 7g) in shape and rigor.

No behavior change. Pure documentation.

What it adds

docs/architecture/code-quality/dependency_policy.md (334 LOC)

  • §1 The rule — every feature is additive; every default has a written justification; every optional dep is reachable via dep:<name> + at least one cfg(feature) use-site; every cross-version duplicate is either in deny.toml [bans].skip-tree with a one-line reason or accepted by multiple-versions = \"warn\" and inventoried in §5.1.
  • §2 The lint posture — no new clippy lints; cargo deny, cargo machete, cargo vet, cargo tree -d, and cargo doc --all-features together enforce the contract.
  • §3 Feature flag contract (playbook §988) — the four-line contract every feature must document in both rustdoc and Cargo.toml.
  • §4 Dependency hygiene rules — direct deps, workspace pinning, optional deps, consumer-side default-features = false overrides, default features on internal crates.
  • §5 Cross-version duplicate acceptance criteria — three reasons the workspace runs multiple-versions = \"warn\" not "deny"; inventory of 12 distinct duplicate groups (4 listed, 8 warn-only) at SHA 4c6ffcff4.
  • §6 Per-crate feature registry — 3 features across 3 of 14 crates; 11 crates intentionally feature-less.
  • §7 Anti-patterns — subtractive features, default-on without justification, orphan optional deps, feature-on-feature without rustdoc cascade, unlisted cross-version duplicate, direct dep without use-site.
  • §8 Audit cadence — per-phase rerun + polars-bump rerun + annual workspace-health review.
  • §9 Cross-references — workspace deps, deny.toml, supply-chain/, audit script, companion policies, playbook, baseline.
  • §10 Decisions log — append-only entries for 8a, 8b, 8c.

CONTRIBUTING.md — new ## Feature flag and dependency policy section (15 LOC)

Mirrors the existing 3 policy sections in CONTRIBUTING (panic, allocation, trait): one-line rule, four-line §988 contract, taxonomy summary (F1/F2/F3/F4/F5), cross-link to dependency_policy.md.

Verifications

  • ✅ All 8 cross-link paths in dependency_policy.md verified to resolve (panic_policy.md, allocation_policy.md, trait_policy.md, lint-posture.md, ../../../clippy.toml, ../../dev/architecture/code_clean/phase_8_...md, ../../../deny.toml, ../../../supply-chain/config.toml).
  • ✅ Pre-commit lint-fast gate green (3 s).
  • ✅ Pre-push gate green (4 s — docs-only fast-path, bucket 2 skipped).

Phase-8 rules adherence

    1. No suppression hacks — pure documentation; zero #[allow] or lint-config changes.
    1. Surgical, correct fixes — single new policy doc + 15-LOC CONTRIBUTING section, no other changes.
    1. Preserve behavior & contracts — zero source / Cargo / dep changes; this PR is doc-only.
    1. Improve tests, don't dodge them — N/A (doc-only); existing test surface unchanged.
    1. Document & commit well — single atomic commit; comprehensive cross-references to companion policies, deny.toml, supply-chain/, audit script, playbook, and the captured baseline.

Refs #195.

…s-link (Phase 8c, refs #195)

Adds the fourth code-quality policy doc for the workspace, mirroring
the shape of panic_policy.md (Phase 5e), allocation_policy.md
(Phase 6f), and trait_policy.md (Phase 7g).

dependency_policy.md sections:

  * §1 The rule — every feature is additive; every default has a
    written justification; every optional dep is reachable via
    `dep:<name>` + at least one `cfg(feature)` use-site; every
    cross-version duplicate is either in skip-tree with a one-line
    reason or accepted by `multiple-versions = "warn"" and
    inventoried in §5.1.
  * §2 The lint posture — no new clippy lints; `cargo deny`,
    `cargo machete`, `cargo vet`, `cargo tree -d`, and
    `cargo doc --all-features" together enforce the contract.
  * §3 Feature flag contract (playbook §988) — the four-line
    contract every feature must document in both rustdoc and
    Cargo.toml.
  * §4 Dependency hygiene rules — direct deps, workspace pinning,
    optional deps, consumer-side `default-features = false"
    overrides, default features on internal crates.
  * §5 Cross-version duplicate acceptance criteria — three reasons
    the workspace runs `multiple-versions = "warn"" not "deny";
    inventory of 12 distinct duplicate groups (4 listed, 8 warn-only)
    at SHA `4c6ffcff4".
  * §6 Per-crate feature registry — 3 features across 3 of 14 crates;
    11 crates intentionally feature-less.
  * §7 Anti-patterns — subtractive features, default-on without
    justification, orphan optional deps, feature-on-feature without
    rustdoc cascade, unlisted cross-version duplicate, direct dep
    without use-site.
  * §8 Audit cadence — per-phase rerun + polars-bump rerun + annual
    workspace-health review.
  * §9 Cross-references — workspace deps, deny.toml, supply-chain/,
    audit script, companion policies, playbook, baseline.
  * §10 Decisions log — append-only entries for 8a, 8b, 8c.

CONTRIBUTING.md gains a 15-LOC "Feature flag and dependency policy"
section mirroring the existing 3 policy sections (panic, allocation,
trait): one-line rule, four-line §988 contract, taxonomy summary,
cross-link to dependency_policy.md.

All cross-link paths verified to resolve.  No behavior change; pure
documentation.  Pre-commit `lint-fast" gate green (4 s).

Refs #195.
@githubrobbi githubrobbi merged commit b867f33 into main May 19, 2026
18 checks passed
@githubrobbi githubrobbi deleted the docs/dependency-policy-phase-8c branch May 19, 2026 19:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant