Skip to content

Add CONTRIBUTING.md, issue/PR templates, and a red-before-fix contributor workflow #70

Description

@plx

Parent

#33

Problem

The project has no contributor guide or issue/PR templates. A new contributor or coding agent cannot discover the supported toolchain, full validation matrix, test-placement rules, dependency/licensing steps, security boundary, or the issue dependency protocol. That makes regression quality depend on oral context and is especially risky for the planned long sequence of one-ticket remediation PRs.

Required outcome

Add a practical CONTRIBUTING.md and GitHub templates that encode the project’s expected workflow:

  1. Supported Rust/MSRV setup, locked dependency installation, and any required auxiliary tools with version/pinning policy.
  2. Repository orientation (excluding the work-in-progress static site from this tool’s audit scope), build/test/lint/doc/package/fuzz/property/mutation commands, and supported-OS expectations.
  3. A mandatory regression workflow for defect fixes: first add the smallest test that demonstrably fails for the reported reason on the parent commit, then implement the fix, then run focused and full validation. Explain how the PR should show or record the pre-fix failure without committing a deliberately broken state to main.
  4. Rules for temporary files and hermetic tests, symlink/platform feature gating, deterministic fixtures, bounded fuzz seeds/corpora, and avoiding tests that touch a developer’s global Cargo/git state.
  5. How to select one issue, honor native blocked by/sub-issue relationships, avoid bundling unrelated findings, link Fixes #N, and update normative docs when contracts change.
  6. Security-report routing, dependency/license attribution updates, release-sensitive file review, and prohibition on exposing tokens/path-sensitive fixtures.
  7. Issue forms/templates for bugs and contract proposals; a PR template with problem, before/after behavior, red-before-fix evidence, validation commands/platforms, docs/compatibility/security impact, and dependency links.
  8. A maintainer section for labeling, triage, review expectations, closing native dependencies, and escalating decisions rather than guessing.

Tests and validation

  • Execute every setup/validation command from a clean clone or equivalent clean worktree on the declared MSRV and current stable Rust.
  • Add a lightweight CI check that required PR-template headings and valid template YAML/front matter remain present.
  • Open a draft test issue/PR (then close it) or use GitHub’s template preview to verify templates render and route correctly.
  • Have an agent unfamiliar with the repository follow only one representative remediation ticket plus CONTRIBUTING.md; record any missing prerequisite needed to produce a conforming PR.
  • Link/lint all contributor documentation.

Acceptance criteria

  • A contributor can set up and run the complete relevant validation suite from the document alone.
  • Defect PRs must provide red-before-fix evidence and focused/full post-fix validation.
  • Templates capture compatibility, security, documentation, and dependency impacts.
  • Agent and human contributors can follow the native issue graph without hidden process knowledge.
  • All documented commands are exercised and stay current in CI.

Dependencies

Blocked by #55, #57, #60, and #63 so the documented platform, fuzzing, toolchain, and release commands are real and stable.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1Significant semantic, completeness, correctness issues.component: docsREADME, specifications, security, and contributor documentationcomponent: governanceRepository controls, ownership, and maintenance policycomponent: test-infraFixtures, property tests, fuzzing, coverage, and benchmarksdiscovered-by-codexIssues discovered via review by codex.domain: governanceProject policy, support, ownership, and release authoritydomain: usabilityCLI experience, diagnostics, installation, and contributor experienceproduction-readinessPart of the audited path from prototype to production-ready userelease-blockerMust close before the production-readiness release gate can passtarget: v0.2.0Must be resolved or explicitly waived before the v0.2 production auditworkflow:production-readinessIncluded in automatic production-readiness work selectionworkflow:production-readiness-leafIndependently actionable work item in the production-readiness sequence

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions