版本发布管理

本页介绍 DataFusion 的发布分支与向后移植（backport）。关于维护者发布指南，包括发布候选制品、投票与发布，参见 dev/release 中的发布流程 README。

概述

DataFusion 通常每月发布一个主版本，其中包含破坏性 API 变更。补丁版本则按需发布，但由于主版本发布较为频繁，我们尽量避免发布补丁版本。

新的开发工作在 main 分支上进行。发布则从名为 branch-NN 的发布分支进行，例如 50.x.y 发布系列对应 branch-50。

总体而言：

新功能进入 [main]
补丁版本从相应的 branch-NN 切出
只有有针对性、低风险的修复才应加入发布分支

改动通过以下两种方式之一进入发布分支：

（最常见）先在 main 上修复问题，再将合并后的改动向后移植到发布分支
先在发布分支上修复问题，再将该改动向前移植到 main

版本发布通过 GitHub issue 进行协调。每个计划中的发布都列在 DataFusion Releases 跟踪 issue 中，每次发布都在专门的 issue 中协调，例如 50.3.0 的发布 issue。如果你认为某个修复应包含在补丁版本中，请在相关跟踪 issue 上讨论，或提交一个向后移植 PR 并在此处链接。

为准备新的发布系列，维护者需要：

在 Apache 仓库中从 main 创建新分支，例如 branch-50
继续向 main 合并新功能
通过向后移植工作流更新版本号、变更日志内容以及任何额外的发布相关修复，为发布分支做准备
从发布分支构建发布候选制品
获批后，发布到 crates.io、ASF 分发服务器以及 Git 标签

向后移植标准

发布分支是为即将发布或刚刚发布的补丁版本准备的稳定化分支。因此，将改动合入发布分支的标准比合入 main 的标准更高，而不是更低。以下标准定义了哪些改动有资格进行向后移植；下文的向后移植工作流描述了具体操作流程。

DataFusion 遵循 Cargo 语义化版本规范，破坏性变更只允许出现在大版本号更迭时——关于公共 Rust API 与 SQL API 稳定性的完整政策，请参阅 API 健康政策。补丁版本（x.y.z，z ≥ 1）只包含修复，绝不引入新功能或破坏性变更。

可以回移植的内容

安全修复。 已知或已报告的安全问题的修复，应当回移植到所有仍在积极维护的发布分支。
正确性修复。 修复产生错误结果、panic、数据丢失或崩溃的查询。如果修复本身需要改变用户可见的 SQL 语义才能把错误结果纠正为正确结果，请遵循下文的行为变更。
稳定性与回归修复。 修复当前发布周期引入的回归、挂起、死锁、内存泄漏或其他可用性问题。
构建、CI 与测试修复：保持该分支能够构建和发布所必需的修复。
文档修复：针对发布版本中已有行为的文档修复。仅存在于 main 分支上的行为，其文档不应放到发布分支。

不建议回移植的内容

新功能，包括新的 SQL 函数、新的优化器规则、新的配置项、新的公共 API 以及新的文件格式支持。这类改动应进入 main，并在下一个大版本中发布。
破坏性 API 变更，无论是 Rust 还是 SQL 层面。DataFusion 只在大版本号更迭时做破坏性变更——参见 API 健康政策。
重构与清理：本身并不修复缺陷的改动，即使改动是正确的也不应回移植。
性能改进：若不属于正确性或稳定性修复，不应回移植。这类改动应进入 main。
依赖升级：除非升级本身就是安全或正确性修复，且没有更小范围的替代方案。

行为变更

“行为变更”是指任何改变用户可见结果的修复：SQL 语义（取值、排序、类型、空值处理）、下游用户可能依赖的错误信息、执行计划输出，或默认配置值。

在发布分支上，行为变更类修复需要格外审慎，因为在补丁版本之间升级的用户并不期望自己的查询突然返回不同的结果。当你提议将此类修复回移植时，需要在发布跟踪 issue 中说明为什么该变更应当随本次补丁版本发布，而不是等待下一个大版本。变更前后的两种行为都应当已在原始 issue 或 PR 中记录——请直接链接过去，不要重复描述。

如有疑虑，默认选择“先进入 main，在下一个大版本发布”。

由谁决定

当前发布线的发布经理是补丁发布内容的最终评审者。他们通过发布跟踪议题进行协调（例如 50.3.0 的发布议题）。任何人都可以提出回移：发起一个回移 PR，并在跟踪议题中链接它；是否纳入由发布经理决定。

活跃发布分支

DataFusion 不维护长期支持（LTS）分支。通常只有最新的 branch-NN 分支会为回移而被积极维护，但如果你需要旧版本中的修复，我们也愿意讨论。

安全修复是例外：维护者可以选择将关键安全修复回移到更早的分支，即使该分支原本已停止维护。在这样做之前，请先在开发邮件列表或跟踪议题中讨论。

回移流程

通常的流程是：

先在 main 上修复，并通过常规 PR 流程合并该修复。
将合并后的提交 cherry-pick 到发布分支上。
发起一个以该发布分支为目标的回移 PR（示例如下）。

所需信息

要回移一项变更，请收集以下信息：

目标分支，例如 apache/branch-52
发布跟踪议题的 URL，例如 https://github.com/apache/datafusion/issues/19692
原始 PR 的 URL，例如 https://github.com/apache/datafusion/pull/20192
（可选）要回移的明确提交 SHA

执行回移

从目标发布分支开始，创建一个专门的回移分支，然后使用 git cherry-pick。例如，当提交 SHA 为 abc123、需要将 PR devlive-community/knowforge#1234 回移到 branch-52 时，运行：

git checkout apache/branch-52
git checkout -b alamb/backport_1234
git cherry-pick abc123

测试

按照测试文档中的说明运行测试。

提交 PR

向发布分支（而非 main）提交 PR，并在标题前加上 [branch-NN]，以标明该回溯修复的目标发布分支。例如：

[branch-52] fix: validate inter-file ordering in eq_properties() (#20329)

PR 描述中应链接跟踪问题、原始 PR 及目标分支，例如：

- Part of <tracking-issue-url>
- Closes <backport-issue-url> on <branch-name>

This PR:

- Backports <original-pr-url> from @<author> to the <branch-name> line

发布管理