|
| 1 | +# Contributing to Codifide |
| 2 | + |
| 3 | +Codifide is MIT licensed and accepts contributions. This document covers the practical steps. |
| 4 | + |
| 5 | +For the full governance model — stewardship, spec-change process, personas, forks — see `GOVERNANCE.md`. |
| 6 | + |
| 7 | +## Before you start |
| 8 | + |
| 9 | +- Read `README.md` and `GETTING_STARTED.md` to understand the project. |
| 10 | +- If you are an AI agent, start with `docs/FOR_AGENTS.md` and `docs/AGENT_QUICKREF.md`. |
| 11 | +- Run the test suite to confirm your environment is clean: |
| 12 | + ```bash |
| 13 | + python3 -m codifide test |
| 14 | + ``` |
| 15 | + All 289 tests should pass. |
| 16 | + |
| 17 | +## Types of contributions |
| 18 | + |
| 19 | +### Additive contributions (no dispatch required) |
| 20 | +- New example programs in `examples/` |
| 21 | +- New tests in `tests/` |
| 22 | +- Documentation fixes and clarifications that do not amend the spec |
| 23 | +- Bug fixes that do not change observable language behavior |
| 24 | + |
| 25 | +These merge on the usual basis: tests pass, code matches the house style, existing examples still run. |
| 26 | + |
| 27 | +### Language changes (dispatch required) |
| 28 | +Any change that affects the capability manifest — new primitives, new AST kinds, new error classes, new effect labels, new surface syntax — requires: |
| 29 | + |
| 30 | +1. A proposal as a paired Quill readout (`.readout.md`) and Glyph dispatch (`.yaml`) in `dispatches/`. |
| 31 | +2. An adversarial Sable audit if the change touches security-adjacent surface (the store, the parser, the effect checker). |
| 32 | +3. Approval from Douglas Jones on the spec amendment. |
| 33 | + |
| 34 | +See `GOVERNANCE.md §Decision-making` for the full process. |
| 35 | + |
| 36 | +### Spec changes |
| 37 | +Changes to `docs/CANONICAL.md`, `docs/CAPABILITY.md`, or any other file that defines conforming behavior follow the same process as language changes above. |
| 38 | + |
| 39 | +## How to submit |
| 40 | + |
| 41 | +1. Fork the repository. |
| 42 | +2. Create a branch from `main`. |
| 43 | +3. Make your changes. Run `python3 -m codifide test` — all tests must pass. |
| 44 | +4. If your change adds new language surface, run `python3 -m codifide dispatch-check` to confirm dispatch pairs are complete. |
| 45 | +5. Open a pull request with a clear description of what changed and why. |
| 46 | + |
| 47 | +## Code style |
| 48 | + |
| 49 | +- Python: follow the existing style. No external formatter is enforced, but match the surrounding code. |
| 50 | +- Rust: `cargo fmt` before committing. |
| 51 | +- Documentation: plain, precise language. No marketing copy in spec files. |
| 52 | +- Commit messages: imperative mood, one line summary, detail in the body if needed. |
| 53 | + |
| 54 | +## Tests |
| 55 | + |
| 56 | +Every new primitive, AST kind, or behavior change needs a test. The test suite lives in `tests/`. Look at existing tests for the pattern — most are short `.cod` fixture programs run through the interpreter with an expected output or error. |
| 57 | + |
| 58 | +## Questions |
| 59 | + |
| 60 | +Open an issue in the repository. For trademark or commercial licensing questions, contact Codifide Inc. directly via [codifide.com](https://www.codifide.com). |
0 commit comments