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.
ADR process
- Open an ADR in
docs/adr/using the MADR format. - Announce in the relevant Slack channel so the team can review async.
- Wait for majority 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 |