You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by po...@apache.org on 2026/04/25 16:43:40 UTC
(airflow) branch main updated: Document Helm Chart branch model and 1.2x.x bugfix flow (#65837)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 0168619c173 Document Helm Chart branch model and 1.2x.x bugfix flow (#65837)
0168619c173 is described below
commit 0168619c173dae4f5884d716445eaea66dc16cc8
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Sat Apr 25 18:43:32 2026 +0200
Document Helm Chart branch model and 1.2x.x bugfix flow (#65837)
Codify the chart's two-branch development model in both the contributor
guide and the dev doc:
* `main` = Airflow Helm Chart 2.x: dropped deprecations, restructuring,
and the in-progress extraction of optional features from the core
chart into separate Kustomize overlays.
* `chart/v1-2x-test` = 1.2x.x maintenance line.
Add explicit 2.0 scope items mirrored from the Apache Confluence Release
Plan (drop Airflow <3.1, Kustomize overlays, drop in-chart DB, Helm 4.0
review, multi-instance per namespace), with a pointer to the wiki as
the source of truth.
Add a "Contributing a bug-fix that should land in 1.2x.x" section that
walks contributors through the three scenarios (bug in both lines vs.
1.2x.x-only vs. main-only) and documents the existing
`backport-to-chart/v1-2x-test` label, which the generic
automatic-backport workflow already handles end-to-end. Update the
committer-side instructions to apply the label before merging.
---
contributing-docs/10_working_with_git.rst | 27 +++++++
dev/README_HELM_CHART2_DEV.md | 123 +++++++++++++++++++++++++++++-
2 files changed, 147 insertions(+), 3 deletions(-)
diff --git a/contributing-docs/10_working_with_git.rst b/contributing-docs/10_working_with_git.rst
index 9a95afbd490..49b61359eae 100644
--- a/contributing-docs/10_working_with_git.rst
+++ b/contributing-docs/10_working_with_git.rst
@@ -63,6 +63,33 @@ The production images are released in DockerHub from:
* ``2.*.*``, ``2.*.*rc*`` releases from the ``v2-*-stable`` branch when we prepare release candidates and
final releases.
+Airflow Helm Chart branches
+---------------------------
+
+The Airflow Helm Chart follows a different branch model from Airflow core, because
+the chart's major version cadence is independent of Airflow's:
+
+* ``main`` — development branch for the next **Airflow Helm Chart 2.x** major release.
+ This is where deprecations are *removed*, restructurings land, and a number of
+ optional features are being **extracted from the core chart into separate
+ kustomizable overlays** (users will compose them on top of the rendered chart with
+ ``kustomize`` instead of toggling them via ever-growing ``values.yaml`` keys). PRs
+ with new features, refactorings, or breaking changes for the chart should target
+ ``main``.
+
+* ``chart/v1-2x-test`` — maintenance branch for the **1.2x.x** release line. This
+ branch is **strictly for bug-fixes, doc-fixes, and deprecation warnings** that give
+ 1.2x.x users notice before features are removed in 2.x. No new features, no
+ restructurings, and no overlay extractions land here. ``1.2x.x`` chart releases are
+ cut from this branch.
+
+The full workflow — which PRs target which branch, which commits are cherry-picked
+across, milestones, and the umbrella refurbish project — is documented in
+`dev/README_HELM_CHART2_DEV.md <../dev/README_HELM_CHART2_DEV.md>`__. Read it before
+opening a chart PR. The current 2.0 scope and chart release schedule live on the
+`Release Plan <https://cwiki.apache.org/confluence/display/AIRFLOW/Release+Plan>`__
+wiki page, which is the source of truth as the plan evolves.
+
How to sync your fork
=====================
diff --git a/dev/README_HELM_CHART2_DEV.md b/dev/README_HELM_CHART2_DEV.md
index afa92659772..9b777515979 100644
--- a/dev/README_HELM_CHART2_DEV.md
+++ b/dev/README_HELM_CHART2_DEV.md
@@ -21,6 +21,8 @@
**Table of contents**
- [Main branch is Airflow Helm Chart 2.x](#main-branch-is-airflow-helm-chart-2x)
+ - [What changes between 1.2x.x and 2.x](#what-changes-between-12xx-and-2x)
+ - [Scope of Helm Chart 2.0](#scope-of-helm-chart-20)
- [Contributors](#contributors)
- [Why separate branches?](#why-separate-branches)
- [Developing for Airflow Helm Chart 2.x](#developing-for-airflow-helm-chart-2x)
@@ -48,6 +50,65 @@ Airflow Helm Chart `1.2x.x` releases will be cut from [chart/v1-2x-test](https:/
> This separates stability (test branch) from preparation for the next major release (main).
> Each cleanup/deprecation task is tracked via individual tickets linked to the umbrella issue.
+## What changes between 1.2x.x and 2.x
+
+The 2.x line is not just a version bump. The refurbish work converging on `main` includes:
+
+* **Dropped deprecations.** Long-deprecated values, templates, and behaviours that have
+ carried warnings through the 1.2x.x line are removed in 2.x. Anything you remove on
+ `main` should land with a deprecation warning on `chart/v1-2x-test` first (when
+ feasible) so 1.2x.x users get one release of notice before the breaking change in 2.x.
+* **Slimmer core chart, kustomizable overlays for optional features.** A number of
+ features that today live inside the chart as feature-flagged templates and `values.yaml`
+ knobs are being moved out of the core chart and into **separate kustomizable overlays**.
+ The core chart on `main` is being trimmed to the components every Airflow deployment
+ needs; opt-in features (extra integrations, optional sidecars, niche deployment shapes,
+ etc.) ship as overlays that users layer on with `kustomize` on top of the rendered
+ chart. This keeps the core chart smaller and easier to reason about, while preserving
+ the functionality through a composable mechanism instead of an ever-growing
+ `values.yaml`.
+* **Restructuring and renames** that would be too disruptive to ship to 1.2x.x users
+ (template layout, value-key reorganisations, defaults that change behaviour) — these
+ belong on `main` only and are explicitly **not** backported.
+
+> [!IMPORTANT]
+> When you propose a change on `main`, decide up-front which of the three buckets it
+> falls into and call it out in the PR description: (1) bug-fix or doc-fix that should
+> also be cherry-picked to `chart/v1-2x-test`, (2) deprecation that lands on
+> `chart/v1-2x-test` as a warning and on `main` as a removal, or (3) `main`-only
+> restructuring / overlay extraction that 1.2x.x users will not see.
+
+## Scope of Helm Chart 2.0
+
+Concrete in-scope items for the first 2.x release, captured from the
+[Release Plan](https://cwiki.apache.org/confluence/display/AIRFLOW/Release+Plan)
+on Apache Confluence:
+
+* **Drop support for Airflow `< 3.1`.** The 2.x chart will only target Airflow 3.1+,
+ which lets us remove the compatibility branches that today bridge 2.x and 3.x
+ Airflow on the same chart.
+* **Cut out complex features and document Kustomize.** This is the overlay extraction
+ work referenced above: features that don't belong in every deployment move out of
+ the core chart, and the chart docs gain a Kustomize section explaining how users
+ compose them back in.
+* **Drop in-chart DB support, document a "simple" Postgres container setup, and use
+ it in our own CI.** The bundled Postgres/MySQL subcharts go away; users running a
+ trivial dev/test setup get a documented standalone Postgres container recipe, and
+ CI switches to that recipe so the chart itself stays focused on Airflow.
+* **Review bumping the default Helm tooling to 4.0.**
+* **Consider supporting multiple Airflow instances in a single Kubernetes namespace.**
+
+> [!NOTE]
+> The release plan is the source of truth and continues to evolve ("More to come..." per
+> the wiki). Treat the list above as a snapshot — when in doubt about whether something
+> is in scope for 2.0, check the wiki page or ask on the dev list rather than relying
+> on this file.
+
+The 1.2x.x release line on `chart/v1-2x-test` continues in parallel on its own
+cadence (the next 1.2x.x release at the time of writing is 1.22.0). The exact dates
+move; the [Release Plan](https://cwiki.apache.org/confluence/display/AIRFLOW/Release+Plan)
+holds the current schedule.
+
# Contributors
The following section explains which branches you should target with your PR.
@@ -71,8 +132,6 @@ PRs should target `main` branch.
## Developing for Airflow Helm Chart 1.2x.x
-PR should target `chart/v1-2x-test` branch.
-
> [!IMPORTANT]
> The `chart/v1-2x-test` branch is **strictly for maintenance, stability, and compatibility**.
> No new features will be added here.
@@ -84,6 +143,50 @@ PR should target `chart/v1-2x-test` branch.
> `1.2x.x` will be the latest release of Airflow Helm Chart 1.2x series.
> We will not cut any new major release from `chart/v1-2x-test` branch.
+### Contributing a bug-fix that should land in 1.2x.x
+
+Where you open the PR depends on **where the bug exists**. Pick one of the three:
+
+1. **The bug exists in both `main` (2.x) and `chart/v1-2x-test` (1.2x.x).**
+ This is the common case for any bug that has been around for a while.
+ * Open the PR against **`main`**, with the fix and tests for 2.x.
+ * Add (or ask a maintainer to add) the **`backport-to-chart/v1-2x-test`** label to
+ the PR. After your PR is merged to `main`, the
+ [Automatic Backport](../.github/workflows/automatic-backport.yml) workflow uses
+ [`cherry-picker`](https://github.com/python/cherry-picker) to open a follow-up
+ backport PR against `chart/v1-2x-test`. You'll see a comment with the link.
+ * **If the cherry-pick conflicts**, the bot leaves the failed cherry-pick on a branch
+ and posts a comment. The committer (or you, if you're comfortable) needs to open
+ a manual PR against `chart/v1-2x-test` with the equivalent fix. Mention the
+ original `main` PR number in the description so the two are linked.
+
+2. **The bug exists only in `chart/v1-2x-test` (1.2x.x), not on `main`.**
+ This happens when the buggy code has already been removed, rewritten, or extracted
+ to an overlay on `main` as part of the 2.x refurbish.
+ * Open the PR directly against **`chart/v1-2x-test`**.
+ * In the PR description, briefly explain why the fix doesn't apply to `main` (e.g.
+ "the affected template was removed in 2.x as part of the Kustomize overlay
+ extraction in #NNNNN"). This saves the reviewer the cross-check.
+ * **No** `backport-to-...` label — there is nothing to forward-port.
+
+3. **The bug exists only on `main` (2.x), not in any released 1.2x.x.**
+ This is the case for regressions introduced by the refurbish work itself.
+ * Open the PR against **`main`** as a normal bug-fix.
+ * **No** backport label.
+
+> [!TIP]
+> If you're not sure which bucket your bug falls into, default to scenario 1 (target
+> `main` and add `backport-to-chart/v1-2x-test`). The committer reviewing the PR will
+> drop the label if the backport doesn't apply, which is cheaper than figuring it out
+> up-front.
+
+The `backport-to-chart/v1-2x-test` label is the chart equivalent of
+`backport-to-v3-2-test` for Airflow core (see
+[README_AIRFLOW3_DEV.md](README_AIRFLOW3_DEV.md)). The `automatic-backport.yml`
+workflow is generic — it strips the `backport-to-` prefix from any label and
+cherry-picks the merge commit to a branch with that name — so the label is already
+wired end-to-end with no chart-specific code.
+
# Committers / PMCs
The following sections explains the protocol for merging PRs.
@@ -93,6 +196,14 @@ The following sections explains the protocol for merging PRs.
PRs should target `main` branch.
We will cherry-pick relevant changes to `chart/v1-2x-test` branch if we decide that they are relevant to the latest release.
+Before merging, decide whether the change should be backported to `chart/v1-2x-test`
+according to the policy in the next section. If yes, **add the
+`backport-to-chart/v1-2x-test` label** before merging. The
+[Automatic Backport](../.github/workflows/automatic-backport.yml) workflow runs on
+push to `main`, reads the label off the merged PR, and opens a backport PR against
+`chart/v1-2x-test` automatically. If the cherry-pick conflicts, the workflow comments
+on the original PR with the failure — the committer then either resolves the conflict
+themselves and opens a manual backport PR, or asks the original author to do so.
## What do we backport to `chart/v1-2x-test` branch?
@@ -103,12 +214,18 @@ We will not backport new features or refactorings.
* **Cleanup/Deprecations** cherry-pick according to version deprecation policy.
* Each minor version of Airflow Helm Chart will include some level of deprecation warnings.
* These warnings will mainly aim to be dropped at 2.0.0.
- * If agreed cleanup/deprecation is relevant to the latest release, it should be cherry-picked to `chart/v1-2x-test` branch.
+ * If agreed cleanup/deprecation is relevant to the latest release, the *warning* (not
+ the removal) should be cherry-picked to `chart/v1-2x-test` so 1.2x.x users see one
+ release of notice before the feature disappears in 2.x.
* **Bug-fixes** cherry-pick only those relevant to the latest chart release and not difficult to apply.
* **CI changes** cherry-pick most CI changes to keep the bugfix branch up-to-date and CI green.
* **Documentation changes** cherry-pick only if relevant to the latest chart release and not about features only in `main`.
* **Refactorings in active areas** do not cherry-pick.
* **New features** do not cherry-pick.
+* **Extracting features into kustomizable overlays** do not cherry-pick. Removing a
+ feature from the core chart on `main` because it has been re-shipped as an overlay
+ is a breaking change for 1.2x.x users — those features stay in the core chart on
+ `chart/v1-2x-test` until 2.x.
## [How to backport PR with `cherry-picker` CLI](README.md#how-to-backport-pr-with-cherry-picker-cli)