redis-py 发布说明生成指南：基于 PR 标签的变更分类与人工核对规范

redis-py 发布说明生成指南基于 PR 标签的变更分类与人工核对规范【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py本文档是 redis-py 仓库维护团队在生成 GitHub Release Notes 时使用的权威标签分类规则完整定义了PR 标签 → 发布说明章节的映射关系、无标签变更的类别推断方法以及与标签无关的排除规则和配套模板约定。读者尤其是仓库贡献者与维护者读完本文后可以独立完成收集发布区间内的 PR → 逐条分类 → 组装符合 redis-py 发布惯例的变更清单这一完整流程并理解为什么这套流程刻意不依赖 release-drafter 等自动化输出。一、为什么需要一套人工分类规范redis-py 仓库本身配置了 release-drafter见 .github/workflows/release-drafter.yml 与 .github/release-drafter-config.yml但其产出不被采纳为发布说明的唯一依据。原因在技能文档 SKILL.md 中写得很明确自动化工具会漏掉 PR也会错误分类 PR。因此发布说明的起草流程规定从 git 历史中自行收集发布区间内的提交/PR而不是读取 release-drafter 的草稿用本文档的规则逐条人工分类以配套的 release-notes-template.md 为骨架组装最终草案。可以对照仓库中的 release-drafter-config.yml 观察自动化配置与本文档规则的异同release-drafter 通过 autolabeler 按文件路径与分支名自动打标签bug-*分支 →bug、maintenance-*分支 →maintenance、feature-*分支 →feature、仅改动*.md与.github/*→maintenance并提供了与本文档一致的类别标签映射。这套自动化仅作为辅助最终归属判断仍以本文档的人工规则为准。二、类别标签决定变更进入哪个章节的权威映射以下标签是唯一能把一个提交放进某个发布说明章节的标签。当 PR 同时携带多个类别标签时必须在每个匹配的章节下列出它——每个章节一行例如一个同时带deprecation和breakingchange的 PR会同时出现在 ⚠️ Deprecations 与 Breaking Changes 两个章节。章节映射标签何时将该 PR 归入此章节 New Featuresfeature,enhancement新增了 Redis 命令、客户端能力、公开选项或对既有行为做出了用户可见的增强。 Experimental Featuresexperimental新增了预览/实验性能力尚未纳入兼容性保证范围代码或测试中通常也标记为experimental。 Breaking Changesbreakingchange修改或移除了任何公开契约函数/方法签名、参数名、默认值、返回类型、抛出的异常类型、线上协议/响应形状或持久化/连接配置——凡是会让从最新已发布版本升级的用户受损的变更都算。⚠️ Deprecationsdeprecation将公开 API、选项或行为标记为弃用但本版本仍保持其可用典型做法是发出DeprecationWarning。如果同一个 PR同时还移除/修改了另一项公开契约则它还要额外出现在 Breaking Changes两处都列出。 Bug Fixesfix,bugfix,bug,BUG修正了受支持功能中的错误行为、崩溃、资源泄漏或回归。 Maintenancemaintenance,dependencies,documentation,docs,testingCI/发布工具链、依赖升级、文档、测试、重构、类型标注/代码风格清理——没有用户可见的行为变化。优先级顺序的用途上表顺序仅在PR 没有类别标签、必须靠推断选定唯一章节时使用见第四节。一旦 PR 携带了类别标签就严格按多标签多章节规则处理与优先级无关。2.1 多标签 PR 的实际示例PR 同时带deprecation与breakingchange同一行内容分别出现在 ⚠️ Deprecations 和 Breaking Changes 两个章节。PR 带feature且同时做了破坏性修改出现在 New Features 与 Breaking Changes。一个同步实现与一个异步实现成对出现的变更详见第六节两行内容分别进入各自类别章节但通常会按配套模板的分组规则合并为一行。三、仓库中存在的、需要显式决策的标签redis-py 仓库还维护着一批不属于上述类别标签的标签。仅带这类标签的 PR 无法自证所属章节必须按下述规则路由同时建议在可行时为 PR 补上正确的类别标签方便日后追溯bug-fix— 按 Bug Fixes处理是bug/fix的同义词建议额外补打bug标签。security— 默认归入 Bug Fixes如果该修复改变了公开契约则改判 Breaking Changes。无论归属哪个章节都强烈建议在## ✨ Highlights中单独点名并附上 advisory/CVE 编号。techdebt— 归入 Maintenance。deprecation— 路由到⚠️ Deprecations章节即类别表。但如果该 PR 在本版本中直接移除或修改了公开契约不只是警告则应归入 Breaking Changes。主题/领域标签——async、cluster、windows、redis-7、redis-py-5、RediSearch、RedisJSON、RedisGraph——描述的是变更作用在哪里而非变更属于哪类。它们永远不会单独决定章节只带这类标签的 PR 仍需按下文规则做出类别决策。四、被排除的标签与非发布标签skip-changelog— 带有该标签的 PR彻底从发布说明中排除。这一约定同样体现在 release-drafter-config.yml 的exclude-labels中说明该标签在人工流程与自动化配置中语义一致。流程/分诊类标签永不进入发布说明分类时直接忽略triage、question、discussion、duplicate、stale、help-wanted、good first issue、need more info、needs-information、ready-for-merge、changes-requested、waiting-for-response、docs-review、update-docs、run-benchmark、hacktoberfest-accepted、tracking-issue。五、无标签时如何推断类别当 PR/提交没有类别标签时根据变更本身推断章节。每一条匹配的规则都要应用——单个变更可以落入多个章节例如它同时弃用一个 API 又破坏另一个 API则同时出现在 Deprecations 与 Breaking ChangesNew Features建议标签feature— 新增 Redis 命令、客户端/连接能力或公开选项或明显用户可见的增强。标题常以feat/feature/add开头。Experimental Features建议标签experimental— 明确是预览/实验性功能代码中标记 experimental、测试位于experimental标记之下或声明为 preview。Breaking Changes建议标签breakingchange— diff 针对最新发布版修改/移除了公开签名、参数名、默认值、返回类型、抛出的异常类型或线上协议/响应形状或 PR 标题/正文出现 breaking、remove、drop support 等字样。Deprecations建议标签deprecation— 将公开 API/选项/行为标记为弃用但保持可用例如新增DeprecationWarning、docstring 中加 deprecated 说明、或加deprecated标记且本版本并未移除。Bug Fixes建议标签bug— 修正错误行为、崩溃、连接/资源泄漏或回归。标题常以fix开头分支名常为bug-*。Maintenance建议标签maintenance— 其余一切没有用户可见行为变化的变更只改动*.md、.github/*、docs/、tests/、pyproject.toml、dev_requirements.txt、docker-compose.yml、dockers/、tasks.py以及依赖升级、重构、类型标注/代码风格清理或 CI 改动。分支名常为maintenance-*。分支命名的推断提示bug-*分支 → Bug Fixesmaintenance-*分支 → Maintenancefeature-*分支 → New Features只改动*.md或.github/*→ Maintenance。这些命名约定与仓库 release-drafter-config.yml 中 autolabeler 的正则分支规则完全一致可互相印证。无法确定时的处理当类别确实模棱两可时不要在草稿中默默猜测——在草稿里留下!-- TODO: confirm category for #N --注释记录不确定性并主动反馈给用户以便 PR 能被正确打标签。六、sync/async 配对变更的分组约定redis-py 大量功能同时提供同步与异步asyncio两套实现。一个行为变更经常以成对的同步/异步工作形态落地且通常在一个 PR 内完成仓库中redis/与redis/asyncio/目录并存即为佐证例如同步 redis/client.py 与异步 redis/asyncio/client.py 中的对应实现。若同一变更由两个独立 PR一个同步、一个异步实现则视为一个变更在相同类别下合并为一行两个 PR 号放入同一个括号组例如- title (#3434 #3456)该分组规则的定义与格式细节以 release-notes-template.md 为准。七、与发布说明模板的衔接章节顺序、行格式与完整骨架分类完成后的组装阶段遵循配套模板 release-notes-template.md。关键约定如下与本文档的分类规则形成闭环章节固定顺序 New Features → Experimental Features → Breaking Changes → ⚠️ Deprecations → Bug Fixes → Maintenance空章节直接省略。每行格式- $TITLE (#$NUMBER)即 PR 标题原文 空格 (#pr号)。同一变更的 PR 分组到一行所有相关 PR 号放入一个空格分隔的括号组并按升序排列如- title (#3434 #3456 #3467)只对真正同一变更的 PR 分组不得为缩短列表而合并无关工作若被分组的 PR 落入了不同类别则在每个匹配章节各放一行。排除skip-changelog的 PR。多类别 PR 在每个匹配章节各列一行与本文档第二节规则一致。手写补充章节## ✨ Highlights仅在发布有重大看点显著新特性或可能影响大量用户的破坏性变更时由维护者撰写位于分类章节之前常规补丁版本不写。贡献者页脚以感谢语开头后接所有被收录 PR 作者去重后的handle列表例如Wed like to thank all the contributors who worked on this release! handle1 handle2 handle3模板还给出了三种已发布形态的样例作为参照主/次版本8.0.0 风格含多个###的 Highlights、预发布8.0.0b2 风格开篇为破坏性变更导读段并链接迁移指南、补丁版本8.0.1 风格只有 Bug Fixes 与 Maintenance且省略所有空章节。八、源码佐证DeprecationWarning 与 experimental 标记在代码中的落地分类规则中提到标记弃用通常发出DeprecationWarning这一约定在 redis-py 源码中有完整的工具链支撑可作为判断 PR 类别的代码级依据redis/utils.py 中的warn_deprecated()与deprecated_function()装饰器前者统一构造 Call to deprecated X -- Deprecated since version Y. 格式的DeprecationWarning后者同时支持同步与异步函数inspect.iscoroutinefunction分支并自动带上调用位置stacklevel。同一文件中的warn_deprecated_arg_usage()与_get_filterable_args()用于对参数级弃用发出警告并支持按allowed_args排除白名单参数。experimental标记在代码与测试中大量出现redis/commands/core.py、redis/commands/search/、redis/cluster.py、redis/asyncio/cluster.py等均有引用对应实验性功能在代码/测试中也标记为experimental的分类提示。因此当你在评估某个无标签 PR 时若发现 diff 中调用了deprecated_function/warn_deprecated或引入了标有 experimental 的 API即可据此分别推断为 Deprecations 或 Experimental Features。九、落地流程速览将本文档规则放入完整流程中细节见 SKILL.md一份发布说明草案的产出路径是确定发布区间以发布分支为输入用git describe --tags --abbrev0 branch找到最近的上一个v*标签。收集提交git log --oneline --no-merges prev-tag..branch从每个提交标题中提取(#pr号)。读取 PR 元数据通过gh pr view n --json number,title,labels,author等只读方式获取标题、标签与作者发布说明行使用 PR 标题而非裸提交主题。逐条分类有类别标签 → 按第二节多章节规则列出只有非类别标签或无标签 → 按第三、五节推断带skip-changelog→ 排除。组装草案按 release-notes-template.md 的章节顺序、行格式、分组规则与贡献者页脚拼装空章节省略。核对以 PR 号而非行数交叉核对收录数量与提交区间一致确认章节顺序与标题合规确认每个 PR 号真实可解析、每个贡献者只出现一次。本文档与配套模板共同构成 redis-py 发布说明的完整分类 → 组装规范前者解决每个变更属于哪个章节后者解决章节如何排序、行如何书写、最终如何成稿两者缺一不可。【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考