Skip to content

docs: add a contributor guide with recipes for adding a lowering rule, a pass and a compiler #965

Closed

Description

@OmarAlJarrah

Problem

A first contribution here goes through more rules than its contributor is told about up front. At c387e25c:

  • Reading. The root guidance, the README and the documents the guidance says to read first come to 74,854 words, about 5.4 hours at 230 words a minute.
  • Rules. The root guidance states 58 rules. 14 are fully mechanized, 16 partly, and 28 (48%) are prose only.
  • Learned by failing. Three throwaway contributions, each built and run through the suite, met rules one failure at a time:
    • A second compiler took 2 new files plus 2 edited ones. The layering test failed first with "not allowed for compilers", which does not say a rules entry is missing. The 100% coverage gate then flagged a loop that only a fault-injection seam reaches.
    • A normalizing pass took 2 new files plus 3 edits. Two tests pin the exact pass list (engine/passes_test.go, cmd/morphic/validate_test.go). Replacing a type in a pass trips the registry rule (pass: give transform passes a sanctioned way to replace and remove types #966).
    • One OpenAPI lowering rule (as fix(compilers/openapi): map sized integer formats to primitives #728 did) touched 6 files: the format table, its test, the conformance case and its spec, a regenerated golden, and a 531-character insertion into one 13,557-character line of ir-design.

Direction

A proposal: a CONTRIBUTING.md that gives three recipes, each a checklist with the commands to run:

  • add a lowering rule;
  • add a pass;
  • add a compiler.

Each step names the test that fails when it is missed. The guide links the design documents rather than restating them. The root guidance keeps the rules and points newcomers at the recipes first.

Done when each recipe, followed literally on a clean checkout, ends with make gate green.

Out of scope

Changing any rule.

Related: #963, #966, #967

Priority: P4, rule 1 (a docs task). wc -w CLAUDE.md README.md docs/architecture.md docs/ir-design.md docs/emitter-design.md docs/ir-spec-matrix.md docs/prior-art.md docs/reference-learnings.md docs/micro-compiler-design.md docs/micro-compiler-plan.md | tail -1 → 74854 total (morphic @c387e25c).

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:P4Refactors, tests, CI, hostile-input hardening, cosmetic diagnostics, other formatstype:docsDocumentation only

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions