Skip to content

chore: add release branch backport workflow and contributing guide - #1747

Merged
SAKURA-CAT merged 5 commits into
mainfrom
docs/workflow
Aug 21, 2026
Merged

chore: add release branch backport workflow and contributing guide#1747
SAKURA-CAT merged 5 commits into
mainfrom
docs/workflow

Conversation

@SAKURA-CAT

Copy link
Copy Markdown
Member

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.Y label 的 PR 后,自动 cherry-pick 并向目标 release 分支创建 [backport] 前缀的 PR;冲突时在原 PR 下留言。
  • 新增 scripts/backport.sh 与 Makefile backport 目标:手动兜底命令 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

  • backport 脚本:已用 PR fix: reset online client singleton after run finish to avoid stale sid #1744release/v0.8 实跑完整链路验证(cherry-pick 冲突处理、push、PR 创建成功,验证后已关闭并清理);参数校验、工作区干净校验、重复 backport 拦截均已验证。
  • Check 聚合 job:YAML 语法校验通过;未在真实 PR 上触发验证(workflow 需合入 main 后才生效)。
  • 未运行 Python / Go 单元测试:本次改动仅涉及 CI、脚本与文档,不涉及产品代码。

Notes

  • backport workflow 读取默认分支定义,需合入 main 后生效;label 自动化依赖 backport release/vX.Y label(v0.7、v0.8 均已创建)。
  • release/vX.Y 分支上 swanlab/package.json 残留的 dev 版本号为切分支遗留,本次未处理(遗留问题),实际发布版本以 tag 构建时覆写为准。
  • ruleset 侧可将 Check 配置为 required status check,两个 CI 因 paths 互斥,同名 Check 可同时覆盖 Python 与 Core 两类 PR。

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 SAKURA-CAT added the 💪 enhancement New feature or request label Aug 21, 2026
@SAKURA-CAT SAKURA-CAT self-assigned this Aug 21, 2026

@SAKURA-CAT SAKURA-CAT left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

审核结论: 评论

本次 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、Makefile backport 目标、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 上提前验证;手动脚本路径已由作者用 #1744release/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.Ypull_title 输入合法;cherry_picking: auto 正确处理 squash 合并;冲突时默认在原 PR 留言(与文档描述一致)
  • 重复 backport 拦截逻辑复核通过:fixed-string (#N) 有括号边界,squash/merge commit 的 -m 1 判断正确
  • PR Actions 全绿(25 个 job,含两个新 Check job 在本 PR 上实跑通过)
  • uv run ruff check . / uv run basedpyright / uv run pytest 未运行(改动仅涉及 CI、shell 脚本与文档,无 Python 代码变更)

Comment thread CONTRIBUTING.md
Comment thread .github/workflows/backport.yml Outdated
Comment thread .github/workflows/backport.yml
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.
@SAKURA-CAT
SAKURA-CAT merged commit af917f6 into main Aug 21, 2026
26 checks passed
@SAKURA-CAT
SAKURA-CAT deleted the docs/workflow branch August 21, 2026 07:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

💪 enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant