diff --git a/docs/source/contributor-guide/release_management.md b/docs/source/contributor-guide/release_management.md index 0515204a5ecbc..d1ef1c0fda67c 100644 --- a/docs/source/contributor-guide/release_management.md +++ b/docs/source/contributor-guide/release_management.md @@ -59,6 +59,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: @@ -121,3 +196,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