Edit content/en/contributing.md on GitHub ↗
Contributing
This page is the operating contract for every change to Fledge, whether it comes from a person or an automation.
Roles
| Role | May do | Must not do |
|---|---|---|
| Owner | Everything; deploy; rotate keys; change policy | — |
| Maintainer | Triage, claim, implement, open PRs, run gates, merge within the gates | Deploy, change quotas on live users, rotate keys |
| Reviewer | Read the diff at a tip, re-run the gates, post PASS / INC / REQUEST_CHANGES | Push code, edit the implementer's PR body |
| Release manager | Assemble fragments, bump the version, tag, publish | Change product code |
| Contributor | Pick an agent-ready issue, write a test, open one PR |
Push to main, merge their own PR |
The author of the tip never PASSes it. A PASS never replaces green CI.
The loop
issue → claim → branch/worktree → red test → fix → gates → PR
→ review at the tip → risk tier → merge queue → release
- Issue. Start from a reproducible defect or a concrete maintenance need. Search open and closed issues first. Include expected behaviour, actual behaviour, a minimal reproduction,
file:linewhere possible, and the environment. - Claim. Skip an issue with a human assignee or a live claim. Assign the maintainer account, add
agent-working, and comment with the branch name and a one-line plan. Heartbeat every 2 hours for long work; release the claim if you stop. - Branch. Branch from the latest
main; use a separate worktree when the local tree is dirty. One issue, one branch, one PR. If a PR already exists, push to that branch. - Red test. Write the smallest test that fails on the unbroken tip. Keep the red output and the green output; a reviewer re-verifies both. Test the class, not one sample.
- Gates. At the exact tip you will link:
npm ci
npm run check
node scripts/risk-gate.mjs --base origin/main
node scripts/changelog.mjs check
Add a changelog fragment for a user-visible change. Update the owned subsystem doc or add Docs-not-needed: to the PR body and a branch commit.
Pull requests
The body states what changed, why, the tip SHA, Ran: and Not run:. A PASS needs at least one real Ran: command. The risk tier comes from the diff; T0/T1 merge on green checks, T2/T3 need a PASS at the same tip. A new commit voids the PASS.
Release
A release manager assembles changelog fragments, bumps the version, creates the tag and publishes. The tag points at the reviewed commit; the release notes list the real changes from the commit range. Never move or delete a tag.
Security and evidence
Never commit or log a token, model key, SMTP password, session cookie, approval token or a full .env. Test evidence must be real: a claimed green test with a failing check is contradicted and blocks auto-merge. Report what you ran, at which commit, and what you did not run.