Skip to main content

Contributor Guide

This guide defines the policies and procedures for contributing to Kargo. Please read it in full before opening issues or pull requests.

Process Overview​

Kargo follows an issue-first contribution model. Unless authored by a maintainer, all code contributions require a linked issue that has been reviewed and unblocked by maintainers in advance.

caution

Ideas and contributions from the community are always welcome, however, items not appearing on the roadmap are reviewed on a best-effort basis. While we cannot guarantee specific timelines or outcomes, we value and consider every submission.

  1. Open an issue using the Bug Report or Feature Request template.

  2. Wait for maintainer review. Maintainers will triage the issue, ask clarifying questions, and determine whether the work aligns with the project's priorities and roadmap.

  3. Wait for the issue to be unblocked. When an issue is ready for external contribution, a maintainer will remove all blocking labels. Do not begin work while any blocking labels are present.

  4. Open a pull request that references the unblocked issue using Closes #<number> in the PR body.

Blocking Labels​

The following labels indicate an issue is not ready for external contribution. Pull requests linked to issues carrying any of these labels will be automatically closed.

LabelMeaning
kind/proposalFeature request under consideration. Not yet unblocked.
needs discussionNeeds further discussion before any work begins.
needs researchNeeds investigation or research before work begins.
maintainer onlyReserved for maintainers due to size, complexity, or sensitivity.
area/securityInvolves security-sensitive code. Maintainer-coordinated only.
size/largeLarge scope. Requires maintainer coordination.
size/x-largeVery large scope. Requires maintainer coordination.
size/xx-largeExtremely large scope. Requires maintainer coordination.

An issue is ready for external contribution when none of these labels are present.

Automatic Enforcement​

Pull requests that do not observe the process described above are automatically closed. This includes:

  • PRs with no linked issue.

  • PRs linked to issues that still carry blocking labels.

  • Unsolicited PRs (no corresponding issue exists).

This enforcement applies to external contributors only. Maintainers are exempt.

Quality Expectations​

All pull requests must:

  • Be authored and reviewed by a human. AI-assisted coding is acceptable, but every line must be understood and verified by the submitter. Submissions that appear to be generated without meaningful human review will be closed.

  • Include appropriate tests for new and modified code.

  • Follow existing code conventions and patterns.

  • Include DCO sign-off on all commits (see Signing Commits).

  • Include documentation updates where user-facing behavior has changed.

Cryptographic signing of all commits is strongly encouraged.

Specific Topics​