Praxis Conventions

A template repository for scaffolding Rust projects with strict, machine-enforced quality standards: opinionated lint configuration, forced testing with high coverage, mutation testing, supply-chain safety, reviewability gates on every PR, and a tag-driven release pipeline.

The conventions-probe crate is a minimal workspace member that keeps every quality gate verifiable against real code. Replace it with real crates when scaffolding a project.

What Is Enforced

• Lints: ~200 rustc/clippy/rustdoc lints at deny, including no unchecked arithmetic, no as casts, no unwrap/panic, exhaustive enum matching, and documentation on every item (public and private)
• Testing: unit + integration tests required; 90% line / 80% region coverage floor; mutation testing; property-based testing conventions
• Supply chain: cargo audit + cargo deny with pinned registries and a license allowlist
• Reviewability: PRs capped at 750 added production lines, with required descriptions, conventional commits, DCO sign-off, and signed commits
• Issue hygiene: new issues are flagged for triage, and anyone assigned to an issue that hasn't been triaged yet is unassigned
• Review hygiene: assignees who owe an initial review are surfaced on the project board and reminded when they are overdue
• Everything else: markdown, TOML, shell, spelling, and workflow files are linted too

Quickstart

Install the requirements, then:

make all            # build + fmt + lint + test + audit
make help           # every available target

Documentation

Document	Contents
conventions.md	Coding style, testing, type design, lint policy
development.md	Requirements, build/test/coverage commands
enhancements	Proposal lifecycle for larger changes
release.md	Versioning, tagging, release pipeline
pr-review-tracker.md	Review response tracking, reminders, rollout
CONTRIBUTING.md	Contributor entry point and PR gates

Scaffolding a New Project

1. Create a new repository from this template
2. Replace crates/conventions-probe with real crates and update members in the root Cargo.toml
3. Update PUBLISH_CRATES and LINT_CMDS in the Makefile, and the crate list in the Containerfile
4. Replace the placeholder owner in .github/CODEOWNERS, the image labels in the Containerfile, and the links in .github/ISSUE_TEMPLATE/config.yml
5. Adjust SECURITY.md supported versions and deny.toml licenses for your dependencies
6. Run make all — every gate should pass before the first commit

Reusing the Workflows

Existing repositories can run these workflows without copying them. Each one below also accepts workflow_call, so a repository keeps a short caller pinned to a tagged commit of this repository:

Workflow	Inputs
pr-conventions.yaml	max-additions, bypass-teams, conventions-doc, commit-subject-pattern, commit-subject-max-length, dco-check, dep-version-check
pr-housekeeping.yaml	stale-draft-days, stale-days
pr-assignees.yaml	maintainer-teams, reviewer-teams
pr-review-tracker.yaml	dry-run, apply-project, apply-reminders, project-number
issue-triage.yaml	policy-doc
automated-review.yaml	pr_number, model, prompt-path, cloud-ml-region, gcp-project-id
publish-dry-run.yaml	make-args
supply-chain.yaml	report-issues, issue-title
coverage.yaml, msrv.yaml, mutants.yaml, semver.yaml	none

supply-chain.yaml runs cargo audit and cargo deny check on push to the default branch and on a daily schedule, not on pull requests. By default it also opens a tracking issue when that run fails, comments on the existing one instead of duplicating it, and closes it when the audit recovers. Pass report-issues: false to turn that off; otherwise pass the PRAXIS_BOT_APP_ID and PRAXIS_BOT_APP_PRIVATE_KEY secrets.

jobs:
  coverage:
    permissions:
      contents: read
    uses: praxis-proxy/conventions/.github/workflows/coverage.yaml@<sha> # v0.5.0

A caller that keeps the default issue reporting also passes the bot secrets:

jobs:
  supply-chain:
    permissions:
      contents: read
    uses: praxis-proxy/conventions/.github/workflows/supply-chain.yaml@<sha> # v0.5.0
    secrets:
      PRAXIS_BOT_APP_ID: ${{ secrets.PRAXIS_BOT_APP_ID }}
      PRAXIS_BOT_APP_PRIVATE_KEY: ${{ secrets.PRAXIS_BOT_APP_PRIVATE_KEY }}

The caller picks the triggers, grants the permissions the called jobs ask for, and passes secrets explicitly. Leave concurrency to the called workflow. Status checks are reported as <caller job> / <job>, so update any required checks in branch rules when a repository switches over.