Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
101 lines (68 loc) · 3.39 KB

CONTRIBUTING.md

File metadata and controls

101 lines (68 loc) · 3.39 KB
Raw

Contributing

Thanks for contributing.

This repository is intentionally governance-first. The fastest way to contribute successfully is to understand the supported architecture and then work through the scaffold, contracts, tests, and docs instead of bypassing them.

Before You Start

Read these files in order before proposing structural changes:

  1. README.md
  2. docs/BLUEPRINT.md
  3. docs/QUALITY_GATES.md
  4. docs/ADD_MODULE.md
  5. docs/RULE_TO_GATE_CATALOG.md
  6. AGENTS.md if you are using AI coding tools in this repo

Development Setup

Prerequisites:

  • .NET 10 SDK
  • Node.js with Corepack and pnpm
  • PostgreSQL
  • mkcert for local HTTPS frontend development if you use Vite dev mode

Install frontend dependencies:

Set-Location web
corepack enable
pnpm install
Pop-Location

Set the database connection string for local work:

$env:ConnectionStrings__BaselineDatabase = "Host=localhost;Database=baseline;Username=postgres;Password=postgres"

Start the application through the supported path:

pwsh ./scripts/Start-ApiHost.ps1

Common Workflows

Add a new module shell:

pwsh ./scripts/New-Module.ps1 -SpecFile templates/module/module-spec.example.json

Before adding a new cross-module *.PublicContracts reference, check headroom against the per-module cap (BP-033):

pwsh ./scripts/Report-ModuleDependencies.ps1

Refresh OpenAPI and generated TypeScript contracts after API changes:

pwsh ./scripts/Generate-Contracts.ps1 -Configuration Release

Run the supported validation wall:

pwsh ./scripts/Invoke-LocalGates.ps1

When you need a targeted rerun after a fix, use the canonical gate dispatcher instead of reassembling raw command lists by hand:

pwsh ./scripts/Invoke-CiGate.ps1 -Id <id>

Use -IncludeSkipped when your local environment can satisfy heavyweight gates that default to skipLocally.

Pull Request Expectations

  • Fix root causes instead of adding compatibility shims.
  • Add or update tests for the behavior you changed.
  • Update docs in the same review when workflow, architecture, setup, or supported scope changes.
  • Keep the governed documentation set synchronized when a governed rule or enforcement path changes.
  • Use the scaffold for structural onboarding. Do not create a new module by copying SampleFeature or KnowledgeBase.
  • Regenerate contracts when browser-consumed HTTP surface changes.

Changes That Need Extra Care

Community Standards

By participating, you agree to follow CODE_OF_CONDUCT.md.

For vulnerability reporting, use the process in SECURITY.md instead of opening a public issue.