Skip to content

Apache DataFusion SQL Query Engine

chore: Define backport criteria (#22766)

Oleks Vd0ee6b5cba5b
diff --git a/docs/source/contributor-guide/release_management.md b/docs/source/contributor-guide/release_management.md
index e01e58a369..7053d0f994 100644
--- a/docs/source/contributor-guide/release_management.md
+++ b/docs/source/contributor-guide/release_management.md
@@ -60,6 +60,81 @@ To prepare for a new release series, maintainers:
- Create release candidate artifacts from the release branch
- After approval, publish to crates.io, ASF distribution servers, and Git tags
+## Backport Criteria
+
+A release branch is a stabilization branch for an imminent or recent patch
+release. The bar for landing a change on a release branch is therefore
+_higher_ than the bar for landing on `main`, not lower. These criteria define
+what is eligible for backport; the [Backport Workflow](#backport-workflow)
+below describes the mechanics.
+
+DataFusion follows Cargo SemVer, with breaking changes allowed at major
+version boundaries — see the [API health policy] for the full framing of
+public Rust and SQL API stability. Patch releases (`x.y.z`, `z ≥ 1`) carry
+fixes only and never introduce new features or breaking changes.
+
+### Eligible for backport
+
+- **Security fixes.** Fixes for known or reported security issues should be
+ backported to every actively maintained release branch.
+- **Correctness fixes.** Fixes for queries that produce incorrect results,
+ panics, data loss, or crashes. If the fix itself changes user-visible SQL
+ semantics to make a wrong result right, follow [Behavior changes] below.
+- **Stability and regression fixes.** Fixes for regressions introduced in the
+ current release line, hangs, deadlocks, memory leaks, or other availability
+ issues.
+- **Build, CI, and test fixes** required to keep the branch buildable and
+ releasable.
+- **Documentation fixes** for behavior already in the release. Documentation
+ for behavior that exists only on `main` does not belong on a release branch.
+
+### Not recommended for backport
+
+- **New features**, including new SQL functions, new optimizer rules, new
+ configuration options, new public APIs, and new file-format support. Land
+ on `main` and ship in the next major release.
+- **Breaking API changes** of any kind, Rust or SQL. DataFusion makes
+ breaking changes only at major version boundaries — see [API health policy].
+- **Refactors and cleanup** that do not fix a bug, even if they are correct.
+- **Performance improvements** that are not also correctness or stability
+ fixes. Land on `main`.
+- **Dependency upgrades**, except when the upgrade itself is the security or
+ correctness fix and there is no narrower alternative.
+
+### Behavior changes
+
+A "behavior change" is any fix that alters user-visible results: SQL
+semantics (values, ordering, types, null handling), error messages that
+downstream users may rely on, plan output, or default configuration values.
+
+Behavior-changing fixes need extra scrutiny on a release branch because
+users upgrading between patch versions do not expect their queries to start
+returning different results. When proposing one for backport, state on the
+release tracking issue _why_ the change should ship in this patch release
+rather than wait for the next major. The previous and new behavior should
+already be documented on the original issue or PR — link to that rather
+than restating it.
+
+If in doubt, default to "land on `main`, ship in the next major."
+
+### Who decides
+
+The release manager for the active release line is the final reviewer of
+what goes into the patch release. They coordinate via the release tracking
+issue (for example, the [release issue for 50.3.0]). Anyone may propose a
+backport by opening a backport PR and linking it from the tracking issue;
+inclusion is the release manager's call.
+
+### Active release branches
+
+DataFusion does not maintain Long-Term Support branches. In general only the
+most recent `branch-NN` is actively maintained for backports, but if you need
+fixes in older releases, we are open to discussion.
+
+Security fixes are an exception: a maintainer may choose to backport a
+critical security fix to an older branch even after it would otherwise be
+closed. Discuss on the dev list or in a tracking issue before doing so.
+
## Backport Workflow
The usual workflow is:
@@ -123,3 +198,5 @@ This PR:
[example backport pr]: https://github.com/apache/datafusion/pull/18131
[additional backport pr example]: https://github.com/apache/datafusion/pull/20792
[testing documentation]: testing.md
+[api health policy]: api-health.md
+[behavior changes]: #behavior-changes