Skip to content

Commit 3401107

Browse files
compheadalamb
authored andcommitted
chore: Define backport criteria (apache#22766)
## Which issue does this PR close? <!-- We generally require a GitHub issue to be filed for all bug fixes and enhancements and this helps us generate change logs for our releases. You can link an issue to this PR using the GitHub syntax. For example `Closes apache#123` indicates that this PR will close issue apache#123. --> - Closes apache#22765 . ## Rationale for this change <!-- Why are you proposing this change? If this is already explained clearly in the issue then this section is not needed. Explaining clearly why changes are proposed helps reviewers understand your changes and offer better suggestions for fixes. --> ## What changes are included in this PR? <!-- There is no need to duplicate the description in the issue here but it is sometimes worth providing a summary of the individual changes in this PR. --> ## Are these changes tested? <!-- We typically require tests for all PRs in order to: 1. Prevent the code from being accidentally broken by subsequent changes 2. Serve as another way to document the expected behavior of the code If tests are not included in your PR, please explain why (for example, are they covered by existing tests)? --> ## Are there any user-facing changes? <!-- If there are user-facing changes then we may require documentation to be updated before approving the PR. --> <!-- If there are any breaking changes to public APIs, please add the `api change` label. --> --------- Co-authored-by: Andrew Lamb <[email protected]>
1 parent fd8b800 commit 3401107

1 file changed

Lines changed: 77 additions & 0 deletions

File tree

‎docs/source/contributor-guide/release_management.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,81 @@ To prepare for a new release series, maintainers:
6060
- Create release candidate artifacts from the release branch
6161
- After approval, publish to crates.io, ASF distribution servers, and Git tags
6262

63+
## Backport Criteria
64+
65+
A release branch is a stabilization branch for an imminent or recent patch
66+
release. The bar for landing a change on a release branch is therefore
67+
_higher_ than the bar for landing on `main`, not lower. These criteria define
68+
what is eligible for backport; the [Backport Workflow](#backport-workflow)
69+
below describes the mechanics.
70+
71+
DataFusion follows Cargo SemVer, with breaking changes allowed at major
72+
version boundaries — see the [API health policy] for the full framing of
73+
public Rust and SQL API stability. Patch releases (`x.y.z`, `z ≥ 1`) carry
74+
fixes only and never introduce new features or breaking changes.
75+
76+
### Eligible for backport
77+
78+
- **Security fixes.** Fixes for known or reported security issues should be
79+
backported to every actively maintained release branch.
80+
- **Correctness fixes.** Fixes for queries that produce incorrect results,
81+
panics, data loss, or crashes. If the fix itself changes user-visible SQL
82+
semantics to make a wrong result right, follow [Behavior changes] below.
83+
- **Stability and regression fixes.** Fixes for regressions introduced in the
84+
current release line, hangs, deadlocks, memory leaks, or other availability
85+
issues.
86+
- **Build, CI, and test fixes** required to keep the branch buildable and
87+
releasable.
88+
- **Documentation fixes** for behavior already in the release. Documentation
89+
for behavior that exists only on `main` does not belong on a release branch.
90+
91+
### Not recommended for backport
92+
93+
- **New features**, including new SQL functions, new optimizer rules, new
94+
configuration options, new public APIs, and new file-format support. Land
95+
on `main` and ship in the next major release.
96+
- **Breaking API changes** of any kind, Rust or SQL. DataFusion makes
97+
breaking changes only at major version boundaries — see [API health policy].
98+
- **Refactors and cleanup** that do not fix a bug, even if they are correct.
99+
- **Performance improvements** that are not also correctness or stability
100+
fixes. Land on `main`.
101+
- **Dependency upgrades**, except when the upgrade itself is the security or
102+
correctness fix and there is no narrower alternative.
103+
104+
### Behavior changes
105+
106+
A "behavior change" is any fix that alters user-visible results: SQL
107+
semantics (values, ordering, types, null handling), error messages that
108+
downstream users may rely on, plan output, or default configuration values.
109+
110+
Behavior-changing fixes need extra scrutiny on a release branch because
111+
users upgrading between patch versions do not expect their queries to start
112+
returning different results. When proposing one for backport, state on the
113+
release tracking issue _why_ the change should ship in this patch release
114+
rather than wait for the next major. The previous and new behavior should
115+
already be documented on the original issue or PR — link to that rather
116+
than restating it.
117+
118+
If in doubt, default to "land on `main`, ship in the next major."
119+
120+
### Who decides
121+
122+
The release manager for the active release line is the final reviewer of
123+
what goes into the patch release. They coordinate via the release tracking
124+
issue (for example, the [release issue for 50.3.0]). Anyone may propose a
125+
backport by opening a backport PR and linking it from the tracking issue;
126+
inclusion is the release manager's call.
127+
128+
### Active release branches
129+
130+
DataFusion does not maintain Long-Term Support branches. In general only the
131+
most recent `branch-NN` is actively maintained for backports, but if you need
132+
fixes in older releases, we are open to discussion.
133+
134+
Security fixes are an exception: a maintainer may choose to backport a
135+
critical security fix to an older branch even after it would otherwise be
136+
closed. Discuss on the dev list or in a tracking issue before doing so.
137+
63138
## Backport Workflow
64139

65140
The usual workflow is:
@@ -123,3 +198,5 @@ This PR:
123198
[example backport pr]: https://github.com/apache/datafusion/pull/18131
124199
[additional backport pr example]: https://github.com/apache/datafusion/pull/20792
125200
[testing documentation]: testing.md
201+
[api health policy]: api-health.md
202+
[behavior changes]: #behavior-changes

0 commit comments

Comments
 (0)