Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
39 lines (28 loc) · 2.49 KB

CONTRIBUTING.md

File metadata and controls

39 lines (28 loc) · 2.49 KB
Raw

Contributing to Cladding

Thanks for your interest in helping make code iron-clad.

GOVERNANCE.md is the canonical guide for how contributions are reviewed, what's in-scope, and what gets rejected. This file is the fast path — read it first, then go to GOVERNANCE.md for the details that govern merge decisions.

Before your first PR

  1. Read GOVERNANCE.md §4 (Contributor Policy). Sections 4.1 (welcome contributions), 4.2 (out-of-scope), and 4.3 (PR contract) are non-negotiable.
  2. Pick an open issue — preferably one tagged good-first-issue. If you have a fresh idea, open an issue first to confirm scope before writing code.
  3. Branch off develop, not main. Naming convention: feature/<short-slug> or fix/<short-slug>.
  4. Run the four-check loop locally before pushing: 
    npm test
npm run typecheck
npm run lint
node bin/clad.mjs check       # 15-stage gate, green on a clean tree
    When you change a stage, a detector, or the conformance contract, also run npm run conformance to re-verify the 26 fixtures. The runner is a contributor self-audit tool — it depends on dev-only toolchain binaries (tsc / eslint / madge / secretlint / vitest), so it works after a contributor install (npm install), not after the end-user install (npm install -g cladding).
  5. Add a CHANGELOG entry under the next-release heading, in the right Keep a Changelog section (Added / Changed / Deprecated / Removed / Fixed / Security).
  6. Open the PR against develop. Releases use a develop → main merge-commit PR followed by a mandatory main → develop back-merge; see GOVERNANCE.md §3.

What kind of contributions land easily

  • Bug fixes with a reproducer test.
  • New conformance fixtures (especially fail-cases that catch drift the current suite misses).
  • New language entries in src/stages/toolchain/detect.ts.
  • Documentation clarity passes — typos, broken links, confusing examples.
  • README translations.

For larger ideas (new detector, new stage, new agent persona, breaking change), open an issue first — GOVERNANCE.md §2 explains the versioning bump that's involved.

Security issues

Do not open a public issue for a security report. See SECURITY.md for the private reporting channel.

Code of Conduct

This project follows the Contributor Covenant v2.1. Be kind, be specific, assume good faith.