Contributing

Quick rules

• Open an issue before a large change; small, focused PRs land fastest
• One concern per PR: keep the diff reviewable
• New behavior ships with tests, and the offline suite passes: python -m pytest tests/ -m "not live"
• Receipts culture: performance and quality claims come with measurements; retrieval-default changes come with benchmark receipts
• Use the software lexicon from docs/ROSETTA.md, not the biology metaphors
• Windows counts: keep subprocess and path handling cross-platform

Issues: no sign-up needed

• Bugs: use the bug report form; it captures the surface, OS, model setup, and installed version we need to reproduce
• Ideas: use the feature request form; capturing the need is enough, no implementation required

Dev setup

$ git clone https://github.com/mbachaud/Cymatix-Context.git
$ cd Cymatix-Context && pip install -e .
$ python -m pytest tests/ -m "not live"

The offline suite (~4k tests) needs no external services. Live tests (-m live) require Ollama running.

PR workflow

1. Fork the repo and branch from master (for example fix/fts5-depth or feat/xpu-backend).
2. Make the change, with tests. Run the offline suite locally.
3. Open a PR against master: say what changed and why, and link the issue it addresses.
4. Checks run automatically: CI plus the Contributor sign-up check. If you have not signed yet, the check fails and a bot comment explains the step.
5. Sign the CLA (next section). The check turns green; comment recheck if it needs a nudge.
6. A maintainer reviews, you iterate, and it merges. Branch protection on master requires the sign-up check, so unsigned PRs cannot merge.

CLA sign-up: one time, on your first PR

There is no form to fill in. The signing interaction happens on your pull request itself:

1. Open your PR. The CLA bot posts a comment and the Contributor sign-up check goes red.
2. Read "What you are agreeing to" below. That is the whole agreement.
3. Reply to the bot's comment with this exact sentence:

I have read the Contributor Guidelines and I hereby sign up as a Cymatix Context contributor

Copy the sentence

• The bot rechecks on its own: the check turns green and your signature is recorded on the repo's cla-signatures branch, covering all your future PRs
• Maintainers are allowlisted and skip the check

What you are agreeing to

• License: your contribution is your own work (or you have the right to submit it), and you license it under the project's Apache-2.0 license, the same license you receive it under
• Standards: you follow the quick rules above: tests, receipts, lexicon, cross-platform