redis-py 发布说明生成指南PR 标签驱动的 Release Notes 草稿工作流【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-pyredis-py 从 4.0.0 起不再维护 CHANGES 文件式的历史记录所有变更都沉淀在 GitHub Releases 中见 CHANGES 文件开头的说明。本文基于仓库内置的generate-release-notes技能完整文档.claude/skills/generate-release-notes/SKILL.md 与其主体 .agents/skills/generate-release-notes/SKILL.md以及两个权威 references 文件系统讲解如何为 redis-py 生成一份与官方发布结构完全一致的 Release Notes 草稿从确定发布分支与区间、收集合并 PR、按标签归类到按模板组装、落地本地文件并完成发布前核验。读完本文你将掌握一套可复用的、不依赖任何自动化 release-drafter 的发布说明起草方法并理解标签体系与发布章节之间的完整映射关系。一、技能定位这份文档解决什么问题generate-release-notes是 redis-py 仓库内置的一套维护者工作流技能其唯一目标是产出一份与项目已发布 GitHub Releases 结构一致的 Release Notes 草稿依据是给定release branch上、自上一个发布以来的合并 PR并按 PR 标签归类。它明确声明Never publish it——草稿只落地为本地 Markdown 文件由维护者审阅后手动粘贴到 GitHub Release 界面发布。该技能文档由三部分构成文件仓库根目录相对路径职责.claude/skills/generate-release-notes/SKILL.md入口与触发说明skill 元信息、触发词全文指向前述 .agents 版本.agents/skills/generate-release-notes/SKILL.md技能主体目标、约束、五步工作流、核验清单.agents/skills/generate-release-notes/references/release-notes-template.md发布说明的章节顺序、标题、行格式与完整骨架.agents/skills/generate-release-notes/references/pr-labels-guide.md权威的标签→章节映射与无标签 PR 的推断规则其中 pr-labels-guide 被文档称为authoritative, self-contained mapping权威且自洽的映射release-notes-template 则拥有章节顺序、标题、行格式、完整骨架的全部定义权。二者共同构成分类与组装的唯一事实来源。一条硬性原则不信任自动化 release-drafter文档明确写道Do not rely on any automated release-drafter output.理由是其会漏掉 PR、且会错误归类。因此技能的每一步收集、归类都必须基于 git 历史手工完成不使用任何自动生成的分类结论。这一点是整套工作流的设计哲学宁可手工逐个确认也不让机器猜测章节归属。两条约束只读 GitHub 访问按仓库 owner 的既定规则未经用户当轮明确授权不得运行任何会产生写入的gh或 GitHub API 调用不创建/编辑 release、评论、标签、tag。数据收集一律使用gh ... view/list、git log或 GET-only 的gh api/curl。文档还提示gh在命令沙箱内可能因 TLS 错误失败必要时需在禁用沙箱的情况下运行。仅写草稿文件技能只在工作树中写一个本地 Markdown 草稿不 commit、不 tag、不 push、不创建 GitHub Release。二、输入与触发方式技能的输入不是版本号而是release branch发布分支——它定义了哪些变更会被纳入本次发布说明。触发方式为自然语言关键词包括release notes、create release notes、generate release notes、draft release notes、prepare release noteschangelog带分支/版本的请求例如release notes for 8.0表示以分支8.0作为 release-branch 输入generate release notes for the 8.0 branch同理询问自上一个 tag 以来改了什么what changed since the last tag任何release notes for X.Y.Z形式的请求都按使用分支 X.Y.Z 作为发布分支来解析。若参数中未提供分支技能会向用户询问绝不猜测。三、完整工作流五步步骤 1确定发布区间与版本确认发布分支存在使用git rev-parse --verify branch验证若是远程分支origin/branch需先 fetch。每个要纳入的变更都是从该分支可达、且从上一个发布 tag 不可达的提交。识别上一个发布 tag取从发布分支可达的最近一个v*tag命令为git describe --tags --abbrev0 branch或用只读的gh release list -L 5辅助。若用户期望不同的基准需与其确认。决定新版本号redis-py 采用major.minor.patch三段式如8.0.1、7.4.1。推断规则是变更集中存在任何 Breaking 或 New Feature至少是 minor 级升版无法确定时与用户确认精确版本。tag 统一采用vversion形式如v8.0.2。当前仓库主版本为 8.x见 redis/init.py 中__version__ 8.0.0这与文档中反复出现的8.0、8.0.1、8.0.0b2示例相印证。步骤 2收集区间内的合并 PR 与提交列出发布分支上自上一 tag 以来的提交git log --oneline --no-merges prev-tag..branch被 squash/merge 的提交标题通常以(#pr-number)结尾从标题中提取 PR 号若项目采用 merge-commit 工作流则改用git log --merges或 GitHub compare API。对每个 PR 号用只读命令获取其标题、标签、作者gh pr view n --json number,title,labels,author # 或 gh api repos/redis/redis-py/pulls/n变更行使用 PR 标题而非原始 commit subject已发布说明采用的就是 PR 标题二者不一致时以 PR 标题为准。剔除任何带有skip-changelog标签的 PR。若某提交没有关联 PRdirect push则以 commit subject 为准并按无标签处理。步骤 3为每个提交归类这是整套技能的核心决策环节依据 pr-labels-guidePR 携带一个或多个分类标签时在每一个匹配的章节下列出——一个带deprecationbreakingchange两个标签的 PR会同时出现在 ⚠️ Deprecations 与 Breaking Changes。PR没有分类标签或只有主题/流程标签、或只有非分类仓库标签如bug-fix、security、techdebt时按 pr-labels-guide 的推断规则确定章节——所有匹配的规则都要应用因此一个变更可能落入多个章节。同时记录你建议为这些 PR 补充的标签。当分类确实存在歧义时在草稿中留下!-- TODO: confirm category for #n --标记并同步给用户而不是默默猜测。步骤 4组装草稿严格遵循 release-notes-template.md以# Changes开头。可选地添加## ✨ Highlights或一个引导性散文段落——仅当本次发布有值得聚焦读者的重大内容时显著新特性或可能影响大量用户的破坏性变更常规补丁版本不写 Highlights。按模板规定的顺序输出分类章节 New Features → Experimental → Breaking Changes → ⚠️ Deprecations → Bug Fixes → Maintenance空章节整体省略。每一行格式为- PR title (#n)。以贡献者页脚收尾感谢语 去重后的author句柄列表。步骤 5保存为本地 Markdown 文件默认路径仓库根目录下的release_notes/release_notes_version.md如release_notes/release_notes_8.0.2.mdrelease_notes/目录不存在则创建用户可指定覆盖路径。不 commit、不 tag、不 push、不创建/编辑 GitHub Release——文件只是本地审阅产物维护者手动将其内容复制进 Release 界面。若release_notes/目录尚未加入 gitignore需提醒维护者避免误提交。文件内容即应粘贴到 Release body 的原文不加任何额外包装或注释。草稿写完后需向用户报告文件路径、版本号、上一 tag、各章节提交数、被推断类别的 PR 数量及具体编号、草稿中遗留的 TODO 标记。四、发布说明模板详解release-notes-template.md章节顺序与对应标签模板规定六个分类章节必须按下表顺序出现并给出哪些标签会把提交路由进该章节顺序章节标题路由进此章节的 PR 标签1## New Featuresfeature、enhancement2## Experimental Featuresexperimental3## Breaking Changesbreakingchange4## ⚠️ Deprecationsdeprecation5## Bug Fixesfix、bugfix、bug、BUG6## Maintenancemaintenance、dependencies、documentation、docs、testing配套规则空章节不渲染没有提交的类别完全不输出补丁版本即是如此。每行格式- $TITLE (#$NUMBER)——PR 标题原样空格括号内为 PR 号。同变更 PR 合并成一行把实现同一功能/变更的多个 PR 合并为一行所有编号放进一个空格分隔的括号组- title (#3434 #3456 #3467)标题取最清晰者通常是主 PR 的。这常见于成对的 sync/async PR、跨多个 follow-up 落地的特性、或修复及其测试/类型标注 follow-up。编号按升序排列。只合并真正属于同一变更的 PR不得为缩短列表而合并无关工作。若被合并的 PR 落入不同章节则在每个匹配章节各放一行同样遵守每章节一行规则。排除任何带skip-changelog标签的 PR。一个 PR 携带多个类别的标签时在每个匹配章节各列一行优先级顺序只用于无分类标签时推断单一章节这一场景。无分类标签的提交先按 pr-labels-guide 推断再放置。可选手写章节## ✨ Highlights仅当发布有重大内容时使用显著新特性或影响面大的破坏性变更。内部使用###散文小节描述每个亮点给出代码/API 名称并链接文档或规格。常规补丁版本没有Highlights。# Changes正下方可放一段无标题的引导散文概括头条变更并链接迁移指南参见 8.0.0b2 预发布版。Highlights/引导段放在生成的分类章节之上。贡献者页脚以感谢语加去重后的句柄列表结尾格式为Wed like to thank all the contributors who worked on this release! handle1 handle2 handle3句柄以空格分隔、去重、每个被纳入 PR 的贡献者出现一次。完整骨架# Changes ## ✨ Highlights ### Notable feature name Prose: what it is, the public API/class/option names, and links to docs or specs. Omit this whole section for routine patch releases. ## New Features - PR title (#n) ## Experimental Features - PR title (#n) ## Breaking Changes - PR title (#n) ## ⚠️ Deprecations - PR title (#n) ## Bug Fixes - PR title (#n) ## Maintenance - PR title (#n) Wed like to thank all the contributors who worked on this release! handle1 handle2已发布版本的三种实战形态模板以三类真实发布形态收尾可直接对照Minor/Major 发布8.0.0 风格# Changes→## ✨ Highlights多个###散文小节覆盖 async cluster pubsub、keyspace notifications、RESP3 默认开启、类型提示重载、连接/重试默认值等→ 分类章节 → 贡献者页脚。预发布8.0.0b2 风格# Changes→ 关于头条破坏性变更的引导散文段附迁移指南链接→ New Features → Breaking Changes → Maintenance → 贡献者页脚。补丁发布8.0.1 风格# Changes→## Bug Fixes→## Maintenance→ 贡献者页脚。无 HighlightsBreaking/Experimental/New Features 等空章节整体省略。五、PR 标签分类指南详解pr-labels-guide.md分类标签决定章节归属以下六类标签是唯一能将提交放入某个章节的标签章节映射标签何时归入此类 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/发布工具、依赖升级、文档、测试、重构、类型标注/lint 清理——无用户可见行为变化多类别标签的 PR 在每个匹配章节各出现一次表内优先级顺序仅用于无标签时的单一章节推断。需要显式决策的仓库标签以下标签存在于 redis-py 仓库但不属于上述分类标签仅带这些标签的 PR 不会自报章节bug-fix—— 视为 Bug Fixesbug/fix的同义词建议同时补打bug。security—— 默认归入 Bug Fixes若修复改变了公共契约则改为 Breaking Changes。无论归入何处都强烈建议在## ✨ Highlights中连同 advisory/CVE 引用一起点名。techdebt—— Maintenance。deprecation—— 路由到 ⚠️ Deprecations若本版本内就移除/变更了公共契约不只是警告则归入 Breaking Changes。主题/领域标签async、cluster、windows、redis-7、redis-py-5、RediSearch、RedisJSON、RedisGraph——只描述变更作用于哪里不描述是什么类型永远不直接决定章节仅带这些标签的 PR 仍需按下方规则做类别决策。排除与流程标签skip-changelog——从发布说明中完全排除该 PR。流程/分诊类标签永远不会出现在发布说明中也不参与分类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。无标签时的推断规则无分类标签时从变更本身推断章节每条匹配规则都要应用一个变更可同时落入多个章节例如既弃用一个 API 又破坏另一个则同时出现在 Deprecations 与 Breaking ChangesNew Features—— 新增 Redis 命令、客户端/连接能力、公共选项或明显用户可见的增强标题常以feat/feature/add开头。建议标签feature。Experimental Features—— 明确为预览/实验性能力代码中标记 experimental、测试位于 experimental 标记下或声明为 preview。建议标签experimental。Breaking Changes—— diff 相对最新发布版变更/移除了公共签名、参数名、默认值、返回类型、抛出的异常类型或线协议/响应形状或 PR 标题/正文出现 breaking、remove、drop support。建议标签breakingchange。Deprecations—— 标记公共 API/选项/行为为弃用但本版本保持可用如添加DeprecationWarning、docstring 中注明 deprecated、或deprecated标记本版本不删除。建议标签deprecation。Bug Fixes—— 修复错误行为、崩溃、连接/资源泄漏或回归标题常以fix开头分支名为bug-*。建议标签bug。Maintenance—— 其余一切无用户可见行为变化的变更只涉及*.md、.github/*、docs/、tests/、pyproject.toml/dev_requirements.txt/docker-compose.yml/dockers//tasks.py、依赖升级、重构、类型标注/lint 清理或 CI分支名为maintenance-*。建议标签maintenance。分支命名提示bug-*→ Bug Fixesmaintenance-*→ Maintenancefeature-*→ New Features只改动*.md或.github/*→ Maintenance。当分类确实模糊时在草稿中留下!-- TODO: confirm category for #N --注释记录不确定性而不是默默猜测并同步给用户以便给 PR 补上正确标签。sync/async 配对 PR 的特殊处理redis-py 同时维护同步栈redis/与异步栈redis/asyncio/两条平行实现一个行为变更经常以成对的 sync/async 工作交付通常合并在单个 PR 内。若两个独立 PR一个 sync、一个 async实现了同一变更则按同一变更处理在相同章节合并为一行两个 PR 号放入同一个括号组- title (#3434 #3456)遵循前述分组规则。这一点也与仓库的双栈结构redis/ 与 redis/asyncio/、测试镜像于 tests/ 与 tests/test_asyncio/相互印证。六、核验与发布前检查技能文档在生成后要求执行以下核验确保草稿与 git 历史严格对账提交数对账所有变更行中引用的去重 PR 号合并行贡献其全部编号加上被排除的skip-changelogPR应等于git log prev-tag..branch中的提交数减去 merge 提交。合并相关 PR 会减少行数但不会减少 PR 引用数因此按 PR 号对账而非按行数。章节核验章节顺序与标题严格匹配 release-notes-template.md且没有输出空章节。引用核验每个被纳入的 PR 号都能解析到真实 PR每个贡献者句柄只出现一次。格式抽检与上一个已发布 release 的排版对照gh release view prev-tag只读。七、仓库相关文件速查以下是本工作流涉及的全部仓库文件均为仓库根目录相对路径可进一步深入研读.claude/skills/generate-release-notes/SKILL.md —— 技能入口、触发词与元信息.agents/skills/generate-release-notes/SKILL.md —— 技能主体目标、约束、五步工作流、核验清单.agents/skills/generate-release-notes/references/release-notes-template.md —— 章节顺序、行格式、完整骨架与实战样例.agents/skills/generate-release-notes/references/pr-labels-guide.md —— 标签→章节权威映射与推断规则CHANGES —— 4.0.0 之前的变更历史4.0.0 之后变更全部追踪于 GitHub Releasesredis/init.py —— 当前版本定义__version__ 8.0.0用于对照文档示例中的 8.x 发布形态redis/ 与 redis/asyncio/ —— sync/async 双栈实现对应分类指南中的 sync/async 配对处理【免费下载链接】redis-pyRedis Python client项目地址: https://gitcode.com/GitHub_Trending/re/redis-py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考