diff --git a/docs/source/contributor-guide/release_management.md b/docs/source/contributor-guide/release_management.md index 0515204a5ecbc..cc0a681eeee8c 100644 --- a/docs/source/contributor-guide/release_management.md +++ b/docs/source/contributor-guide/release_management.md @@ -59,6 +59,86 @@ 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** that correct documentation about 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. Before opening the backport PR: + +1. State on the release tracking issue _why_ the change must ship in this + patch release rather than the next major. +2. Describe the previous and new behavior with example queries and results. +3. Wait for explicit acknowledgment from the release manager or another + committer on the tracking issue. + +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. A branch is +considered closed once the next major release branch has been cut and the +release manager closes its tracking issue; users who need a fix beyond that +point should upgrade to the next major. + +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 +201,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