chore: add release branch backport workflow and contributing guide - #1747
Merged
Conversation
Add a script and workflow to backport merged PRs to release branches via cherry-pick, and add aggregate check jobs to Python and core PR workflows for required status checks.
SAKURA-CAT
commented
Aug 21, 2026
SAKURA-CAT
left a comment
Member
Author
There was a problem hiding this comment.
审核结论: 评论
本次 PR 解决的问题
为历史维护分支引入 backport 机制(label 自动化 + 手动脚本兜底),配套重写贡献指南,并为 Python / Core PR CI 增加聚合 Check job 以支持 ruleset required status check。
审核范围
- 构建、依赖与发布:
backport.yml(新增)、test-python-pr.yml/test-core-pr.yml聚合 Check job、Makefilebackport 目标、scripts/backport.sh - 文档:
CONTRIBUTING.md重写(分支模型、修复策略、Backport 用法、发版流程),相对链接与锚点逐一核对无坏链 - 安全:
pull_request_target+ 第三方 action 权限上下文(见 inline 细节) - 测试与验证: 见下
未涉及 core/**、protos/** 与 Python 产品代码,按构建/CI/文档通用标准审核。
未挂行发现
- 说明: 一旦将
Check配置为 ruleset required status check,不命中两个 CI paths 的 PR(如纯CONTRIBUTING.md改动)将永远不上报Check,会被 ruleset 阻塞合并。届时需补一个 paths 反向匹配的 fallback workflow(上报同名Check),或接受该限制并配合Label/ bypass 机制。 - 说明: label 自动化链路(
pull_request_target读取默认分支的 workflow 定义)需合入 main 后才生效,无法在本 PR 上提前验证;手动脚本路径已由作者用 #1744 →release/v0.8实跑验证。
验证
-
bash -n scripts/backport.sh通过 -
make -n backport(带/不带参数)参数校验与透传正确 - 三个 workflow YAML 解析 +
needs引用校验通过([type-check, test]、[lint, test]均存在) - korthout/backport-action@v4 上游契约核对:默认
label_pattern: ^backport ([^ ]+)$匹配backport release/vX.Y;pull_title输入合法;cherry_picking: auto正确处理 squash 合并;冲突时默认在原 PR 留言(与文档描述一致) - 重复 backport 拦截逻辑复核通过:fixed-string
(#N)有括号边界,squash/merge commit 的-m 1判断正确 - PR Actions 全绿(25 个 job,含两个新
Checkjob 在本 PR 上实跑通过) -
uv run ruff check ./uv run basedpyright/uv run pytest未运行(改动仅涉及 CI、shell 脚本与文档,无 Python 代码变更)
Add a fallback CI workflow to report success for PRs that don't touch Python or Core CI paths, preventing required status checks from blocking merges on such PRs. Also align GitHub Actions backport branch names with the manual backport script convention.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
为历史维护分支(release/v0.7、release/v0.8)引入 backport 机制,并配套更新贡献指南,同时为 Python / Core 两个 PR CI 增加聚合 check job 以支持 ruleset 的 required status check 配置。
Changes
.github/workflows/backport.yml:基于korthout/backport-action的 label 驱动自动化。合并带backport release/vX.Ylabel 的 PR 后,自动 cherry-pick 并向目标 release 分支创建[backport]前缀的 PR;冲突时在原 PR 下留言。scripts/backport.sh与 Makefilebackport目标:手动兜底命令make backport PR=<N> BRANCH=<release-branch>,包含重复 backport 拦截、工作区干净校验、cherry-pick 冲突时保留现场并打印善后指引。test-python-pr.yml/test-core-pr.yml:各新增Check聚合 job(if: always()+needs.*.result判断),前置 job 任一失败/取消即失败,便于 ruleset 配单一 required status check。CONTRIBUTING.md:新增「分支模型与版本维护」章节(分支模型、修复策略、Backport 用法、发版流程);修订分支命名与提交规范为实际仓库风格;补全单元测试、代码风格与类型检查章节,修复原文档中悬空目录与坏锚点。Testing
release/v0.8实跑完整链路验证(cherry-pick 冲突处理、push、PR 创建成功,验证后已关闭并清理);参数校验、工作区干净校验、重复 backport 拦截均已验证。Notes
backport release/vX.Ylabel(v0.7、v0.8 均已创建)。release/vX.Y分支上swanlab/package.json残留的 dev 版本号为切分支遗留,本次未处理(遗留问题),实际发布版本以 tag 构建时覆写为准。Check配置为 required status check,两个 CI 因 paths 互斥,同名Check可同时覆盖 Python 与 Core 两类 PR。