hiredis 维护分支 Backport 实战:从 cherry-pick 到 Release Drafter 自动草稿发布
hiredis 维护分支 Backport 实战:从 cherry-pick 到 Release Drafter 自动草稿发布
hiredis(Redis 官方 C 客户端)通过 release/vX.Y.X 维护分支管理历史发布线的补丁修复。本文以仓库内 backport-pr 技能文档 为核心骨架,完整讲解"评估目标发布线 → 创建主题分支 → cherry-pick → 全量测试 → 提 PR → merge 落地"的逐分支回移植流程,并揭示 Release Drafter 自动生成补丁版本草稿的底层机制。读完本文,你将掌握一套可复制的 hiredis 维护分支 backport 操作规程,并理解为什么这类改动"必须以合并的 PR 形式"才能进入发布草稿的变更日志。
一、机制前提:为什么 backport 必须走 PR
Release Drafter 构建草稿发布中的 $CHANGES 变更清单时,只统计 last-release-tag...branch-head 区间内已合并的 PR。这意味着:
- 直接 push 到维护分支的 commit 永远不会出现在变更日志中,它们唯一的作用是向
$CONTRIBUTORS贡献提交者名单; - commit 与 PR 的关联关系无法事后补建——GitHub 只在一份包含该精确 SHA 的 PR 被合并的那一刻建立关联。
因此,backport 到 release/vX.Y.X 的修复必须以"已合并的 PR"形式到达分支,否则补丁即使合入代码,也不会被列入自动起草的补丁版本发布说明。
仓库内的配套配置印证了这一机制:release-drafter.yml 在 push 到 master 时触发 release-drafter/release-drafter@v7 动作,而 release-drafter-config.yml 中的 template 模板正是由 $CHANGES(变更列表)与 $CONTRIBUTORS(贡献者致谢)两段拼接而成。
二、维护分支的命名与枚举约定
hiredis 的维护分支遵循如下约定:
- 每个发布线一条分支,命名为
release/vX.Y.X,其中X是字面后缀(literalX),例如 1.0 线的分支名为release/v1.0.X; - 分支从该线的发布 tag 创建,例如从
v1.0.2创建release/v1.0.X; - 跳过发布候选版本(RC):枚举需要 backport 的版本线时,
v1.1.0-rc1这类 tag 不应被当作创建基准; - 用远端 tag 而非本地克隆枚举版本:本地克隆的 tag 可能过期,必须使用
git ls-remote --tags查询远端; - 若某条线的维护分支尚不存在,应从该线最新的非 RC tag 创建分支,并先补齐 Release Drafter 配置(见下文第五节),再落地 backport。
以当前仓库的实际 tag 情况为例(git ls-remote --tags origin 可见):v1.0.0-rc1、v1.0.1、v1.0.2 构成 1.0 线,最新非 RC tag 是 v1.0.2,对应分支 release/v1.0.X;1.1 线则包含 v1.1.0-rc1、v1.1.0、v1.1.1,应以 v1.1.1 为基准;后续 v1.2.0、v1.2.1、v1.3.0、v1.3.1、v1.4.0、v1.4.1 依此类推。
三、逐分支 backport 的标准流程
3.1 动手前先评估每个目标发布线
不要急于对每条发布线执行回移植。修复涉及的代码在不同发布线之间可能差异巨大,甚至旧线根本不受影响。正确做法是:在操作任何东西之前,先审查修复内容与每条目标线的代码,确认该线上确实存在脆弱/有缺陷的代码,再决定是否 backport 到该线。
3.2 创建主题分支
从维护分支切出主题分支,命名格式为 backport-<topic>-X.Y.x,例如 backport-nesting-depth-1.0.x:
git checkout release/v1.0.X
git checkout -b backport-nesting-depth-1.0.x
3.3 cherry-pick 保留原作者身份
git cherry-pick <sha>
git cherry-pick 会保留原始提交的作者信息——这正是原始作者能进入草稿发布 Contributors 名单的原因。如果产生冲突,采用最小化解决原则:优先丢弃过时的注释或上下文,而不是重构周边代码。
3.4 构建与全量测试(合并门槛)
每条分支都必须通过构建与完整测试,这是合并的硬性门槛:
make hiredis-test && ./hiredis-test
其中 ./hiredis-test 必须针对真实运行的 Redis 服务器跑完全部测试套件——连接类测试不是可选项。运行测试前先确认服务器在线:
redis-cli ping
若服务器未运行,立即停止并提示用户启动(例如 redis-server --daemonize yes);不得自行启动服务器、不得跳过连接测试、不得在未达到"干净的 -Werror 构建 + 全部测试通过"的情况下继续提 PR。
仓库源码为这条门槛提供了完整佐证:
-Werror是默认开启的:Makefile 中WARNINGS=-Wall -Wextra -Wstrict-prototypes -Wwrite-strings -Wno-missing-field-initializers,且USE_WERROR默认值为 1,未显式关闭时追加-Werror;- 测试目标的真实构成:Makefile 定义了
hiredis-test(链接test.o与 hiredis 静态库)、test(make test后直接./hiredis-test)以及check(TEST_SSL=$(USE_SSL) ./test.sh)三个目标,技能文档采用的make hiredis-test && ./hiredis-test是其中最直接的一步到位方式; - 真实 Redis 服务器由测试脚本拉起:test.sh 会生成临时
redis.conf(含daemonize yes、端口 56379、Unix socket),启动redis-server后轮询等待 socket 文件出现,再以./hiredis-test -h 127.0.0.1 -p 56379 -s <socket>执行全套测试; - 测试套件覆盖面:test.c 的
main()依次执行分配器注入、命令格式化、回复解析、阻塞连接错误处理,以及针对 TCP、Unix socket、SSL(HIREDIS_TEST_SSL)、异步 API(HIREDIS_TEST_ASYNC)、轮询适配器、继承 fd 的各类连接与超时/IO 错误测试;任何失败都会以非零退出码收尾并打印*** N TESTS FAILED ***,全部通过则输出ALL TESTS PASSED。
3.5 提交 PR 与标签
gh pr create --base release/vX.Y.X --head backport-<topic>-X.Y.x
提交 PR 时有三个关键要求:
- 标题即变更日志条目——保持上游 commit 的原始主题(subject);
- 打对标签,使其落入正确的变更日志分类:
bug对应 "🐛 Bug Fixes"、maintenance、feature等;标签必须已存在于仓库中(Release Drafter 只统计已有标签); - 在 PR 描述中致谢原始作者;对于安全修复,还要致谢漏洞报告者(hiredis 的安全漏洞上报渠道见 SECURITY.md,经由 Redis Vulnerability Disclosure Program 接收)。
标签与分类的对应关系可以直接从 release-drafter-config.yml 读到:breakingchange → Breaking Changes、experimental → 🧪 Experimental Features、feature/enhancement → 🚀 New Features、fix/bugfix/bug/BUG → 🐛 Bug Fixes、maintenance → 🧰 Maintenance;同时该配置的 autolabeler(release-drafter-config.yml)会自动为 bug-*、maintenance-*、feature-* 分支以及 *.md/.github/* 文件改动打上相应标签。
3.6 以 merge commit 合并
gh pr merge --merge --delete-branch
必须使用 merge commit(而非 squash 或 rebase) 合并。合并产生的 push 会触发 Release Drafter 工作流,从而更新该分支对应的草稿发布。
3.7 例外:CI/基础设施变更不走 PR
工作流文件(workflows)、Release Drafter 配置等 CI/基础设施变更不提交 PR,而是直接 push 到维护分支;只有功能性 backport 才走 PR 流程。这是刻意为之:这些变更不应进入 $CHANGES 变更日志,直接推送即可。
四、发布草稿的验证方法
backport 落地后,按以下方式验证草稿是否正确生成:
# 查看 Release Drafter 工作流的运行状态
gh run list --workflow "Release Drafter" --branch release/vX.Y.X
# 查看当前所有草稿发布
gh api repos/redis/hiredis/releases --jq '.[] | select(.draft)'
说明:技能文档中的
repos/redis/hiredis是针对上游仓库的写法;实际执行时应替换为当前维护操作所对应的真实owner/repo(本仓库的 git remote 为gitcode.com/gh_mirrors/hi/hiredis.git)。
验证时有两点重要认知:
- 草稿对未认证/低权限 token 不可见——返回空结果可能意味着认证问题,而不是草稿不存在;
- 一份正确的草稿应当满足:版本号指向下一个补丁版本、目标分支是维护分支
release/vX.Y.X、每个 backport PR 出现在其正确分类下、同时致谢 backporter 与原始 commit 作者。
五、已知的坑点(gotchas)
技能文档明确提醒:草稿的版本号会在每次发布后自动自校正,一旦 filter-by-range 机制就位,无需手工固定版本号。换句话说,不要为了"看起来正确"而去手动改草稿版本——发布流程会自动把它推进到下一个补丁版本。
六、命令速查与检查清单
按单条维护分支汇总的完整操作序列:
# 0. 从远端枚举版本线(勿用本地 tag)
git ls-remote --tags origin
# 1. 评估该线上是否确实存在待修复代码
git show release/vX.Y.X:path/to/file
# 2. 创建主题分支并 cherry-pick
git checkout -b backport-<topic>-X.Y.x release/vX.Y.X
git cherry-pick <sha>
# 3. 确认 Redis 在线,构建并全量测试
redis-cli ping
make hiredis-test && ./hiredis-test
# 4. 提 PR(base=维护分支,head=主题分支,标题保持上游 commit 主题,打已有标签)
gh pr create --base release/vX.Y.X --head backport-<topic>-X.Y.x
# 5. merge commit 合并,触发 Release Drafter
gh pr merge --merge --delete-branch
# 6. 验证草稿
gh run list --workflow "Release Drafter" --branch release/vX.Y.X
gh api repos/<owner>/<repo>/releases --jq '.[] | select(.draft)'
逐分支检查清单:修复代码确实存在于该线 ✓ → 分支命名 release/vX.Y.X、主题分支命名 backport-<topic>-X.Y.x ✓ → cherry-pick 保留原作者 ✓ → -Werror 构建干净 ✓ → 真实 Redis 服务器上全量测试通过 ✓ → PR 标签已存在且分类正确 ✓ → 以 merge commit 合并 ✓ → 草稿版本/分支/分类/致谢四项核对无误 ✓。
结语
hiredis 的 backport 流程本质上是"围绕 Release Drafter 机制设计"的:只有合并的 PR 才能进入变更日志,所以每一步——主题分支命名、cherry-pick、标签、merge commit——都在为"自动生成正确的补丁版本草稿"服务。结合 Makefile、test.sh、test.c 与 .github/release-drafter-config.yml 可以确认:全量测试是合并门槛、-Werror 默认开启、分类与标签一一对应。这套流程不仅适用于 hiredis 本体,其"评估 → 回移植 → 测试 → PR → 验证草稿"的模式也值得其他维护多版本线的 C 语言项目借鉴。