roboco/CONTRIBUTING.md

Contributing to RoboCo

Thanks for your interest in contributing. This document explains the contribution workflow and the licensing terms your contributions are made under.

License of contributions

RoboCo is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). Your contributions are accepted into the project under that license.

Contributor License Agreement (CLA)

Before your first pull request can be merged, you must sign the project's Contributor License Agreement.

Why a CLA? The AGPL keeps the published project open. The CLA grants the maintainer the additional rights needed to keep the project's future flexible — for example, to offer a dual-licensed or commercial edition later, or to re-license the codebase if that ever becomes necessary. Without it, the project would be permanently locked to exactly one license, because each contributor would retain sole copyright over their contribution.

Signing the CLA does not transfer ownership of your work away from you — you keep your copyright. It grants the maintainer (and the maintainer's successors and assigns) a broad license to use, distribute, and re-license your contribution. See CLA.md for the exact terms.

How signing works

The first time you open a pull request, the CLA Assistant bot will comment with a link and ask you to confirm agreement by posting a one-line comment on the PR. This is a one-time action; subsequent PRs are recognized automatically.

Development workflow

1. Fork the repository and create a feature branch.

2. Make your change. Follow the existing code style.

3. Run the full quality gate before opening a PR:

   make quality   # ruff format, ruff check, markdown reflow, mypy, pytest --cov-fail-under=80, xenon, radon
   

The gate includes a markdown prose reflow check (scripts/reflow_md.py --check) that rejects hard-wrapped text in docs/ and README.md — prose must follow a one-sentence-per-line standard. If it fails, run make reflow-docs to auto-fix, then re-run make quality. See docs/rag/standards/markdown-reflow-quality-gate.md for details.

For the frontend (panel/):

pnpm format && pnpm lint && pnpm typecheck && pnpm test

4. Sign your commits. master requires verified signatures, so set up commit signing before you push — see Signing your commits.
5. Open a pull request with a clear description of the change and its motivation.

Commit messages

Keep commits focused and descriptive. Do not include AI-generated attribution footers or co-author trailers.

Signing your commits

master is protected by a rule that every commit must carry a verified signature. Set this up once and it's automatic from then on; otherwise a maintainer has to bypass the rule to merge your PR.

This is cryptographic signing (git commit -S, shown as Verified on GitHub) — not the -s Developer Certificate of Origin sign-off trailer. The sign-off does not satisfy the signature rule.

The lowest-friction method reuses the SSH key you already use with GitHub:

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub   # or id_rsa.pub
git config --global commit.gpgsign true

Then add that same public key to GitHub a second time as a signing key: Settings → SSH and GPG keys → New SSH key → Key type: Signing Key. (GPG signing also works if you prefer it.)

Your next commit will be signed; confirm with git log --show-signature -1. If you already pushed unsigned commits on your PR, re-sign the whole branch and force-push:

git rebase --exec "git commit --amend --no-edit -S" origin/master
git push --force-with-lease

Questions

Open a GitHub Discussion or issue if anything here is unclear.