|
| 1 | +<!-- SPDX-License-Identifier: PMPL-1.0-or-later --> |
| 2 | +# Contributing |
| 3 | + |
| 4 | +Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. |
| 5 | + |
| 6 | +## How to Contribute |
| 7 | + |
| 8 | +We welcome contributions in many forms: |
| 9 | + |
| 10 | +- **Code:** Improving the core stack or extensions |
| 11 | +- **Documentation:** Enhancing docs or AI manifests |
| 12 | +- **Testing:** Adding property-based tests or formal proofs |
| 13 | +- **Bug reports:** Filing clear, reproducible issues |
| 14 | + |
| 15 | +## Getting Started |
| 16 | + |
| 17 | +1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. |
| 18 | +2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. |
| 19 | +3. **Task Runner:** Use `just` to see available commands (`just --list`). |
| 20 | + |
| 21 | +## Development Workflow |
| 22 | + |
| 23 | +### Branch Naming |
| 24 | + |
| 25 | +``` |
| 26 | +docs/short-description # Documentation |
| 27 | +test/what-added # Test additions |
| 28 | +feat/short-description # New features |
| 29 | +fix/issue-number-description # Bug fixes |
| 30 | +refactor/what-changed # Code improvements |
| 31 | +security/what-fixed # Security fixes |
| 32 | +``` |
| 33 | + |
| 34 | +### Commit Messages |
| 35 | + |
| 36 | +We follow [Conventional Commits](https://www.conventionalcommits.org/): |
| 37 | + |
| 38 | +``` |
| 39 | +<type>(<scope>): <description> |
| 40 | +
|
| 41 | +[optional body] |
| 42 | +
|
| 43 | +[optional footer] |
| 44 | +``` |
| 45 | + |
| 46 | +Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` |
| 47 | + |
| 48 | +## Reporting Bugs |
| 49 | + |
| 50 | +Before reporting: |
| 51 | +1. Search existing issues |
| 52 | +2. Check if it's already fixed in `main` |
| 53 | + |
| 54 | +When reporting, include: |
| 55 | +- Clear, descriptive title |
| 56 | +- Environment details (OS, versions, toolchain) |
| 57 | +- Steps to reproduce |
| 58 | +- Expected vs actual behaviour |
| 59 | + |
| 60 | +## Code of Conduct |
| 61 | + |
| 62 | +All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). |
| 63 | + |
| 64 | +## License |
| 65 | + |
| 66 | +By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). |
0 commit comments