Maintainer Guide
This guide is for Distro team members and HC owners — those who review PRs, author ADRs, and own chart releases. All general contribution requirements in Contribution & Collaboration apply equally to maintainers.
Roles
HC owners are the designated decision-makers for chart architecture and direction. Distro team members are the reviewers and release owners for all chart modifications. The authoritative list of both is in .github/CODEOWNERS.
Architecture Decision Records (ADRs)
ADRs are required for architectural decisions. Additive config knobs and features that have no architectural or cross-component footprint do not require an ADR — a feature request issue is sufficient.
| Change type | ADR required? |
|---|---|
| New component added to the chart, or feature with architectural / cross-component impact | Yes |
| Architectural or structural change | Yes |
| Directional / cross-team impact | Yes |
| Additive config knob on an existing component (no architectural footprint) | No — feature request issue instead |
| Bug fix / documentation update | No |
Footprint test: if the change forces other components to be aware of it, alters a shared contract (auth, storage, networking), or sets precedent for a class of problem, it needs an ADR. A purely local toggle does not.
ADRs should be rare, durable records of architectural decisions. Capture the stable
problem, decision, constraints, alternatives, and consequences rather than implementation
steps that are likely to change. Prefer an issue, PR description, or operational guide for
tactical changes. Edit an accepted ADR in place only for non-semantic corrections. When
constraints or conclusions change, write a new ADR that links to the earlier decision with
Amends:. When replacing a decision, write a new ADR that links to it with Supersedes:.
ADR process
- Open an ADR in
docs/adr/using the MADR format. - A human author or an AI agent acting on an explicit human request may prepare the draft.
- Announce in the relevant Slack channel so the team can review async.
- Require human review from the Distribution team and affected stakeholders. AI-generated drafts and automated reviews are inputs, not approval.
- Wait for majority human approval from the Distribution team and any affected stakeholders.
- Implement, then open a PR referencing the ADR.
ADRs in docs/adr/ are automatically detected by crev during AI-assisted review. A well-written ADR directly improves the quality of automated review feedback and reduces back-and-forth with human reviewers.
PDP / Kickoff
Major changes with cross-team impact require a design discussion (PDP or kickoff meeting) to define scope, clarify responsibilities, and ensure alignment with existing Helm and Kubernetes design. This complements the ADR — it is not a substitute.
We are currently exploring how to adapt this process as part of Camunda's AI-first operating model. Until a new process is defined, the intention of the PDP/kickoff step should be followed.
PR Review
Ownership
The Distro team is the final reviewer and approval authority for all Helm chart modifications.
For app team PRs:
- Tier 2, well-scoped changes: the app team implements; the Distro team reviews and approves. See Values YAML Policy for Tier 2 definition.
- Larger or architectural changes: Distro may take over implementation after ADR approval, or co-author with the app team.
crev — automated AI review
PRs should be reviewed by crev, an AI code-review tool with domain-specific knowledge of the Camunda Helm charts. After reviewing, crev posts:
- A commit status (
crev/escalation) indicating whether human review is required. - A label (
human-review-requiredorai-review-sufficient) based on the escalation score.
Run crev against the PR before marking it ready for review:
crev https://github.com/camunda/camunda-platform-helm/pull/<pr-number>
All PRs require human approval from the Distro team before merge. Maintainers use the crev/escalation output to inform and prioritise their review — it does not replace it.
Keeping docs/adr/, this guide, docs/contribution-and-collaboration.md, and CONTRIBUTING.md accurate directly improves crev review quality — it uses this corpus as context when reviewing PRs.
Shared Requirements
The following policies apply equally to maintainer-authored changes:
| Topic | Reference |
|---|---|
| PR requirements | Contribution & Collaboration — PR Requirements |
| Tests | Testing Guide |
| Backporting | Backporting Policy |
| Values key classification | Values YAML Policy |
| Breaking changes | Breaking Changes Policy |