Skip to main content

Breaking Changes & Deprecation Policy

Definition of a breaking change​

A breaking change is any change that breaks a previously stable interface/contract and requires user action to upgrade.

Helm chart "Public API"​

For the Camunda Helm chart, the stable interface is values.yaml: user-provided values are rendered by Helm templates into Kubernetes manifests. A change is breaking if it changes how existing values.yaml inputs map to rendered manifests in a way that is not backward compatible.

Classifying changes (examples)​

  • Tier 2 key addition (additive): Adding a new optional Tier 2 (infra/connectivity) field that is additive, opt-in, and defaults to prior behavior is not a breaking change. See Values YAML Policy for the Tier 2 definition.
    • Example: add optional global.gateway.tls.enabled that defaults to false.
  • Tier 1 key addition: Adding a new Tier 1 (application behavior) key to values.yaml is not allowed on any active chart version — regardless of whether it seems additive — because it extends the Helm chart's application-behavior surface in violation of ADR 91. See Values YAML Policy.
  • Bug: A defect that forces users to apply mitigations (overrides/workarounds) to get expected behavior.
    • Example: users must set a specific env var or template override to avoid incorrect behavior.
  • Breaking change: Remove/rename an existing field, or change its meaning/defaults such that upgrades require user updates.
    • Example: deprecate a values.yaml key without backward compatibility.
  • Unstructured override interaction: Changes involving unstructured fields (e.g., <component>.env or extraConfiguration) are typically not breaking API changes to the chart, but can cause upgrade issues due to user-specific overrides; treat resulting incompatibilities as bugs (see Unstructured fields).
    • Example: a user-set env var workaround in extraConfiguration conflicts after an upgrade because the underlying behavior changed.

Breaking Change Policy​

Default rule: The Camunda 8 policy for non-public APIs governs breaking changes to the chart. When a change cannot be made backward compatible, follow the Deprecation Policy.

Migration rule: A deliberately breaking deployment change ships with its automated migration (product-strategy decision-07, decided 2026-09-30 under the Non-Breaking Automated Updates initiative). For the chart, the migration is a Camunda Helm Toolkit migrate rule that rewrites the affected values.yaml inputs, available when the chart version that contains the change is released. The Breaking change checklist carries the step.

Exceptions​

Two narrow exceptions exist where a breaking change is permitted without a deprecation cycle:

  • Alpha charts: Breaking changes are allowed between alpha releases (e.g., 8.9-alpha3 → 8.9-alpha4). However, breaking changes introduced during the alpha cycle must be resolved before the first stable release — the alpha-to-stable boundary (e.g., 8.9-alpha6 → 8.9.0) must be backward compatible with the previous stable minor (e.g., 8.8.x).
  • Critical fix: A breaking change in any released chart (patch or minor) is allowed only to address a critical security vulnerability or severe malfunction where the standard deprecation cycle would leave users insecure or fundamentally broken. Must follow the Breaking change checklist.

All other changes — including architectural improvements, schema simplification, and key removal — must go through the Deprecation Policy regardless of release boundary.

Breaking change checklist​

Evaluate and justify breaking change​

A critical-fix breaking change is justified only if all of the following are true:

  1. No reasonable compatible approach: A backward-compatible design exists only with disproportionate complexity, risk, or long-term maintenance cost (e.g., supporting two schemas/behaviors would be fragile, delay delivery significantly, or create ongoing upgrade/support burden).
  2. Necessary outcome: The change is required to deliver at least one of:
    • a critical fix (security / severe malfunction), or
    • a correctness fix that prevents wrong/unsafe deployments, or
    • an essential architectural/maintainability improvement that otherwise blocks future work.
  3. Customer impact is acceptable and understood: Impacted users can be identified/estimated, and the migration is practical (clear steps; no "guessing" required).
  4. Migration is documented: Exact migration steps exist and can be included in docs/release notes/upgrade guide.

If a breaking change is not justifiable, follow the Deprecation Policy.

Approval / alignment​

  1. Document and align with EM and PM justification of the breaking change (rationale, scope, customer impact, target version).
  2. Mark the change as breaking in the issue and PR (label breaking-change + clear description). See Ticket & Label Policy for the breaking-change label definition.
  3. Notify and align with primary stakeholders:
    • InfraEx and #oc-reliability-testing — closest day-to-day chart users; must explicitly acknowledge before proceeding.
    • QA and infra.
  4. Proceed only once EM/PM approved and all stakeholder teams explicitly acknowledged.

Documentation​

  1. Prepare and publish:
    • Add docs about what changed (breaking behavior) and required customer actions.
    • Add release notes (breaking change callout).
    • Add release announcements (link to docs/migration guidance).
    • Add upgrade guide (steps + links to docs).

Migration​

  1. Ship the automated migration with the change:
    • Add the Camunda Helm Toolkit migrate rule that rewrites the affected values.yaml inputs, and the validate rule that flags inputs the rewrite cannot resolve.
    • Link the toolkit change from the PR and the upgrade guide.

Merge and final internal communication​

Deprecation Policy​

Default rule: The Camunda 8 policy for non-public APIs sets the deprecation window. Every deprecation ships with clear migration guidance.

Major chart releases follow Camunda's release cycle.

Deprecation Checklist​

  1. Deprecate (keep compatibility):

    • Add a values.yaml comment: DEPRECATED since vX.Y.Z; remove in vA.B.C; use instead: ..., where vA.B.C is the first chart version the deprecation window allows.
    • Warn if the deprecated key is set (old key, replacement, removal version). Warnings are collected by the camunda.constraints.warnings helper, which surfaces them on both the CLI path (NOTES.txt on install/upgrade) and the GitOps render path (the <release>-warnings ConfigMap rendered by configmap-warnings.yaml, visible to helm template / Argo CD / Flux). Feed new deprecation warnings through that helper rather than wiring them directly into NOTES.txt.
    • If both old and new are set: new wins + warning.

  2. Document:

    • Release notes: "Deprecations" entry (old → new, removal version).
    • Upgrade guide: migration steps (before/after) + removal version.
    • Examples: use new format only.

  3. Communicate:

  4. Remove (only after the deprecation window):

    • Delete the key, its template references, and the deprecation warning.
    • Follow the approval, documentation, and migration steps from the Breaking change checklist.

Reference​

Unstructured fields​

extraConfiguration is the correct and primary mechanism for injecting application-level configuration into Camunda components (feature flags, log levels, Spring Boot properties, etc.). Per ADR 91 and the Values YAML Policy, <component>.env is a legacy escape hatch — new application configuration should not use it.

Because extraConfiguration entries fall outside Helm's awareness or validation scope, they introduce variability that can affect upgrade stability. For example, if a user overrides an application property via extraConfiguration to work around a previous limitation, and a subsequent chart update or upstream Camunda release resolves that limitation internally, the existing override may conflict with the new behavior.

From a versioning and stability standpoint, this scenario does not constitute a breaking change in the Helm chart's API. The core capability — the ability to inject application configuration — remains stable. However, if the functional outcome in the application layer deviates from expectations, it should be treated as a bug, not a breaking API change.

Framing stability in this way helps maintain consistency in the Camunda Helm chart release process, ensuring that users can rely on values.yaml as the stable interface while understanding the inherent risks of unstructured overrides and Helm's limitations in validating them.

For the backporting policy as it relates to breaking changes, see Backporting Policy.