Skip to content
CommonLayer
Documentation menu
On this page

Contributor handbook

This handbook is for community contributors: people who improve a CommonLayer project without holding a maintainer assignment. It explains how contributions are recorded and reviewed, what recognition they get, and how a contribution can be rewarded from the project's flexible pool. Each project lives in a repository of its own, the first-party ones included (commonlayer-org/base, commonlayer-org/nginx, commonlayer-org/valkey, commonlayer-org/postgresql): open pull requests and issues there, following that repository's docs/CONTRIBUTING.md. For contributing to the platform's code, read CONTRIBUTING.md; for maintainers, the maintainer handbook.

What counts as a contribution

A contribution records community work on a project: a pull request, an issue, a review, a security fix, a documentation change or something else, optionally linked to a vulnerability finding. It is not money; financial contributions are described in the funding model.

Contributions reach the platform in two ways:

  • Tracked pull requests. When a project's repository is linked through the CommonLayer GitHub App, pull requests are tracked, and a merged pull request by a non-bot author becomes a contribution automatically (github.pull_request.merged → maintenance). A pull request's author is matched to a CommonLayer account through a linked GitHub identity (user_identities); unmatched authors are recorded by their GitHub login. This path is tested with GitHub's documented webhook payloads; no real GitHub App has sent one yet.
  • Manual submission. Any signed-in user can submit a contribution with a URL (POST /api/v1/projects/{slug}/contributions). The portal has no form for it yet; use the API with a session or a personal API token.

Authors without a CommonLayer account still count as community for the review statistics, but recognition on a profile and rewards need an account (link your GitHub identity to receive credit for your pull requests).

Review

A maintainer of the project (project.contributions.review) reviews each contribution and marks it approved or rejected with a note (POST /api/v1/contributions/{id}/review; no portal page yet). The reviewer is always a person, never a service account, and nobody reviews their own contribution (database CHECK). Review responsiveness is part of maintainers' monthly evaluation: community pull requests that wait more than seven days for a first maintainer review count against the reviews.responsiveness rule.

Approved public contributions appear on the project's maintenance page (/projects/{slug}/maintenance) and on your public profile (GET /api/v1/users/{username}/contributions).

Rewards from the flexible pool

Each project's allocation policy usually reserves part of the monthly target for the flexible pool (20 % in the default policy). It is the only source of money for community rewards.

  1. A maintainer proposes a reward for an approved contribution, with an amount and a rationale (portal Dashboard → Maintainer → Proposals or the project's Rewards page; POST /api/v1/projects/{slug}/rewards, project.rewards.propose). A proposer cannot propose a reward for themselves, and a contribution carries at most one open or funded reward (409 funding.reward_exists).
  2. Approval (project.rewards.approve, a person, never a service account): one approval up to the platform's single-approval limit (default $100, a runtime setting), two above it, one of which must come from a project admin or a platform admin. The proposer never counts as an approver, whatever the amount, and the recipient never approves (ADR-0045).
  3. On final approval the amount moves from the flexible pool to the project's obligations at once. If the pool does not hold enough, the reward is refused (funding.insufficient_flexible_pool) and nothing is taken from other accounts.
  4. The obligation is paid by the normal payout run, like maintainer compensation. You need a verified payout destination and tax status, but not a maintainer assignment.

Pull requests are never rewarded automatically. A reward is a deliberate, recorded decision by people other than you, and it is public on the project's reward list (GET /api/v1/projects/{slug}/rewards) with its amount and rationale.

No live payouts are configured on any deployment; rewards can be proposed, approved and funded in the ledger, but paying them out requires an operator to enable live payouts (see ledger specification).

Security fixes

If your contribution fixes a vulnerability, link it to the finding. When the fixed release resolves the finding, the finding records the contribution (fix_contribution_id). The maintainers who reviewed and released your fix have met their remediation obligation; the contribution itself is recognised and may be rewarded.

To report a vulnerability privately instead of fixing it in public, use a private security report (portal /security/report, POST /api/v1/security/reports); see SECURITY.md for vulnerabilities in the platform itself.

Becoming a contributor role holder

Approval of a contribution grants the contributor project role (projects.on_contribution_approved, a subscriber of maintenance.contribution.approved; an existing explicit role is kept). The acceptance tests and the seed exercise it (seams::merged_pull_requests_become_contributions_and_approval_grants_contributor). The contributor role currently only allows submitting contributions, which any signed-in user can do anyway.