企业官网建设流程全解析

• 特征工程
• 机器学习
• 数据科学

导读

本文围绕 Featuretools 仓库的 docs/backport_release.md 展开，系统讲解当需要把main分支上的部分提交移植回旧版本并对外发布补丁版本（Backport Release）时，团队遵循的标准化操作流程。你将掌握从发布前共识、创建X.Y.x目标分支、cherry-pick 移植提交、版本号提升、Release Notes 更新，到 GitHub Release 与 conda-forge 同步发布的全套实战步骤，并了解仓库中 CI 配置对这些流程的支撑原理。

上图展示了 Backport Release 的核心形态：main分支从Release v0.11.1演进到Release v0.12.0，期间产生了提交03bfe15；与此同时从v0.11.1分叉出的0.11.x维护分支通过 cherry-pick 将03bfe15移植过来，最终产出补丁版本Release v0.11.2。这正是本文要拆解的全过程。

一、什么是 Backport Release：与常规发布的差异

Featuretools 的正常发布流程记录在仓库根目录的 release.md 中，其大致脉络为：预发布检查 → 评估性能测试 → 创建release_vX.Y.Z分支 → 提升版本号 → 更新 Release Notes → 创建发布 PR → 创建 GitHub Release → 在 conda-forge 发布。

Backport Release 与常规发布的本质区别在于发布的目标提交不同：常规发布以main分支最新提交为目标，而 Backport Release 以某个非最新的旧提交（通常是旧版本 tag）为目标，把新版本中的部分提交反向移植到旧版本线路上再发布。常见的场景有两种：

• 为新版本之间补一个中间补丁版本，例如在已有的0.11.1与0.12.0之间新增一个0.11.2；
• 在已有更新版本之后继续发布一个更旧的补丁版本，例如0.12.0已发布后，再发布0.11.2（此时该补丁版本仍会被 GitHub 标记为“最新 release”，详见后文）。

由于目标分支、移植方式、版本号规则与发布目标都与常规发布不同，Backport Release 需要按本文档的差异流程执行，其余步骤与 release.md 保持一致。

二、第 0 步：发布前检查清单

在启动 Backport Release 之前，需要先在团队内对以下三项达成一致：

• 确定作为发布目标的提交：Backport Release 的目标不是main的最新提交，而是某个更早的提交。很多情况下目标就是旧版本本身，可以直接引用其 tag，例如v0.11.1。
• 确定需要移植的提交清单：明确要从main上挑选哪些提交回移植到旧版本上，这是整个流程的核心输入。
• 确定补丁版本号：为这次 Backport Release 选定要使用的具体版本号。

Backport Release 的版本号规则

Featuretools 遵循语义化版本（Semantic Versioning），版本号形如<majorVersion>.<minorVersion>.<patchVersion>（主版本.次版本.修订版本）。Backport Release 只递增修订号（patch version），绝不改变主版本或次版本。

具体有两种落点：

1. 作为两个既有版本之间的中间版本：例如在已有0.11.1和0.12.0的情况下新增0.11.2；
2. 作为最新补丁版本：例如同样场景下直接发布0.12.1，此时只取 docs/source/release_notes.rst 中 "Future Release" 部分列出的部分提交。

三、第 0.5 步：创建 Backport 目标分支

这一步的产出是一个长期维护用的X.Y.x分支，后续所有 Backport 提交与补丁发布都以它为目标。

3.1 检出目标提交

先检出团队已达成一致的目标提交。如果目标是之前的正式版本，直接检出其 tag 即可：

git checkout v0.11.1

3.2 创建 Backport 分支

从目标提交拉出新分支，分支名取该提交对应的主版本号和次版本号，修订号用x占位。例如目标提交属于0系列第11个次版本，则分支名为0.11.x。

采用这种命名的必要性在于：如果未来还需要针对同一版本线路做更多补丁发布，可以直接复用这个分支作为目标。0.11.x分支在 Backport Release 中扮演的角色，等同于常规发布中的main——它是发布的目标分支。

该分支会被自动保护（除非版本号超过9.Y.x或X.99.x这类扩展场景，此时需要联系仓库团队扩展保护规则），从而避免未经验证的提交悄悄混入发布。

3.3 移植目标提交（Cherry-pick）

1. 从0.11.x分支拉一个功能分支，分支名遵循backport_vX.Y.Z命名规则，例如backport_v0.11.2。这一命名并非随意——仓库的 CI 检查（见 .github/workflows/release_notes_updated.yaml）会把backport_v\d+\.\d+\.\d+这类分支视为“开发分支例外”，从而绕过 release notes 必填检查，该检查要求其余所有 PR 都必须新增一条 release note。
2. 把待移植的提交 cherry-pick 到backport_v0.11.2分支上。
3. 以0.11.x分支为目标创建 Pull Request，确认期望的改动已全部包含，并确认 CI 检查全部通过。
4. 在 docs/source/release_notes.rst 的 "Future Release" 部分写入被移植提交的 release notes（不要从main上原始位置删除它们），并明确标注这是原 PR 的 backport，格式如下：

Future Release ============== * Enhancements * Fixes * Fix bug (backport of :pr:`1110`) * Changes * Documentation Changes * Testing Changes Thanks to the following people for contributing to this release:

5. 将 PR 合并进0.11.xBackport 分支。

关于 CI 的源码佐证：.github/workflows/release_notes_updated.yaml 用正则^main$、^release_v\d+\.\d+\.\d+$、^backport_v\d+\.\d+\.\d+$、^latest-dep-update-[a-f0-9]{7}$、^min-dep-update-[a-f0-9]{7}$匹配分支名；只有不匹配这些模式的分支才会执行grep ":pr:\${{ github.event.number }}`"的 Release Notes 检查。这就是“backport_vX.Y.Z与release_vX.Y.Z` 命名可以绕过检查”的底层原因。

四、第 1 步：创建 Featuretools Backport 发布

此时0.11.x分支已就绪，以它为发布目标，开始产出0.11.2。

4.1 创建 Release 分支

从 Backport 分支0.11.x拉分支（注意不是从main），分支名遵循release_vX.Y.Z命名规则，例如release_v0.11.2。与上一步同理，该命名用于绕过 release notes 必填检查。

4.2 提升版本号

需要同步提升__version__，原文档列出的文件包括setup.py、featuretools/version.py和featuretools/tests/test_version.py。

需要特别说明的是，当前仓库的版本管理已迁移到基于pyproject.toml的动态版本机制：仓库根目录已不存在setup.py，而是由 pyproject.toml 中的version = {attr = "featuretools.version.__version__"}动态读取 featuretools/version.py 中定义的__version__。因此在实际操作中，真正需要修改的权威文件是：

• featuretools/version.py：包含__version__、ENTITYSET_SCHEMA_VERSION、FEATURES_SCHEMA_VERSION三个字段；
• featuretools/tests/test_version.py：测试用例会断言__version__与预期值一致（当前仓库中该测试断言__version__ == "1.31.0"），版本号提升后必须同步更新此断言，否则测试会失败。

4.3 更新 Release Notes

1. 把 docs/source/release_notes.rst 中的"Future Release"替换为当前发布日期：

v0.11.2 Sep 28, 2020 ====================

2. 删除本次发布中用不到的 Release Notes 小节（例如 Fixes、Testing Changes 等空小节）。
3. 把自己加入本次发布的贡献者列表，贡献者必须按字母顺序排列。
4. 发布 PR 本身不需要被写进变更列表。
5. 在当次版本小节上方，新增一段被注释掉的 "Future Release" 小节，包含所有 Release Notes 小节，供下一次发布直接解注使用：

.. Future Release ============== * Enhancements * Fixes * Changes * Documentation Changes * Testing Changes .. Thanks to the following people for contributing to this release:

4.4 创建发布 PR 与合并前检查

发布 PR 的标题必须是版本号（例如v0.11.2），PR 正文放本次发布的 Release Notes，贡献者列表不必包含。需要注意：Release Notes 中的 Sphinx 文档语法:pr:\547`需要改写成 GitHub 链接语法#547`。

合并前逐项确认：

• checkin 测试与0.11.x分支上的所有测试均为绿色；
• 发布 PR 分支的 ReadtheDocs 构建已通过，且产出的文档包含预期的 Release Notes；
• PR 已经过评审并批准；
• 与团队确认：在进入下一步（GitHub Release）之前，0.11.x分支将被冻结，不再合入任何改动。

五、第 2 步：创建 GitHub Release

发布 PR 合并进0.11.x之后，开始起草 GitHub Release，关键字段如下：

• 目标（Target）必须是0.11.xBackport 分支，而不是main；
• Tag为带v前缀的版本号，例如v0.11.2；
• Release 标题与 tag 相同；
• Release 描述为本次发布的完整 Release Notes，包括感谢贡献者的那一行；贡献者链接同样要从文档语法:user:\gsheni`改写为 GitHub 语法@gsheni`；
• 不是预发布（pre-release）；
• 发布（Publish）后会自动将包上传到 PyPI。

关于自动上传 PyPI 的源码依据：仓库的 .github/workflows/release.yaml 在release事件（published类型）触发后，会依次执行构建（python -m build）、通过 Trusted Publisher 机制发布包到 PyPI，并在发布后调用create_feedstock_pr.yaml工作流为 conda-forge 创建 feedstock PR。因此“Publishing the release will automatically upload the package to PyPI”在仓库中是真实可验证的自动化链路。

需要特别提醒：这个 backport 补丁版本会显示在仓库首页的“最新 release”位置，即使技术上存在更新的0.12.0也是如此——因为 GitHub 按 tag 创建时间展示最新 release。团队成员与用户需要留意这一展示差异。

六、在 conda-forge 上发布

与常规发布的差异点在于：如果已有更新的版本（如0.12.0）存在，conda-forge 的机器人不会自动为 backport 版本（如0.11.2）创建新 PR，需要手动在 conda-forge 的 featuretools-feedstock 仓库中创建。手动创建有两种方式：

方式一：从0.11.1的 meta.yaml 更新提交处拉分支

在0.11.1的 meta.yaml 更新提交处拉新分支，基于它做0.11.2的 meta.yaml 修改。这种方式更“干净”，有时也更容易；但如果0.11.1到0.12.0之间新增了迁移文件（如 py310 迁移），则必须自己手动补上并重新渲染（re-render）。

方式二：把0.11.2的改动追加到0.12.0的更新提交之后

在 feedstock 仓库中0.12.0更新提交之后直接追加0.11.2的改动。好处是如果样板（boilerplate）内容有变化，无需手动重新添加（同类做法在 Woodwork 的 backport 发布中已有先例）。

PR 创建完成后：

1. 更新recipe/meta.yaml中的 requirements 变更——如果是自己手动打开 PR，还需要处理版本号、源码链接（source links）和 SHA256 校验值；
2. 测试通过后，由维护者（maintainer）合入 PR。

七、Backport Release 与常规发布对照表

八、仓库中的配套设施与验证证据

Backport Release 流程并非仅停留在文档层面，仓库中有一系列配置与测试直接支撑上述步骤，阅读时可供交叉验证：

• .github/workflows/release_notes_updated.yaml：release notes 检查工作流，通过分支名正则豁免main、release_vX.Y.Z、backport_vX.Y.Z等分支，并在非豁免分支上校验docs/source/release_notes.rst是否包含对应 PR 编号的:pr:记录。
• .github/workflows/release.yaml：监听release的published事件，自动构建并发布 PyPI，随后触发create_feedstock_pr.yaml创建 conda-forge PR，对应文档中“发布即自动上传 PyPI”的表述。
• pyproject.toml：以version = {attr = "featuretools.version.__version__"}动态解析版本号，替代了旧文档提到的setup.py。
• featuretools/version.py与featuretools/tests/test_version.py：版本号的权威定义与一致性断言测试。
• docs/source/release_notes.rst：Release Notes 的实体文件，"Future Release" 占位结构、vX.Y.Z + 日期的版本标题、:user:与:pr:语法均在其中有真实样例。
• docs/pull_request_template.md：PR 模板明确提示，普通 PR 需更新 "Future Release" 部分才能通过release_notes_updated检查，从侧面印证了文档中“命名可绕过检查”的机制。

结语

Backport Release 是 Featuretools 在维护多条版本线路时的关键工程实践：通过X.Y.x长期分支 + cherry-pick 移植 + 约定式分支命名 + 自动化 CI 豁免，团队既能以最小成本修复旧版本的关键问题，又能保持main上的发布历史不被破坏。本文覆盖的检查清单、分支操作、版本号与 Release Notes 规则、GitHub Release 与 conda-forge 发布细节，可直接作为执行一次补丁发布的核对手册使用。

• 特征工程
• 机器学习
• 数据科学