尧图网站建设 
Warp 发布说明自动起草全流程基于 Towncrier 片段的 GitHub Release Notes 生成指南【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp本文以 NVIDIA WarpGPU 加速的 Python 仿真/机器人/机器学习框架仓库中的.codex/skills/warp-release-notes技能为蓝本系统讲解如何从 Towncrier changelog 片段fragment或已打 tag 的最终 CHANGELOG 自动生成 GitHub 发布说明Release Notes草稿。技能负责自动识别 feature / bugfix 发布类型、解析上一个版本标签作为 diff 基准、聚合片段与贡献者归属并产出可直接编辑发布的 Markdown 文档。读完本文你将掌握这套六阶段流水线解析目标版本 → 与用户确认 → 收集输入 → 规划分组 → 起草章节 → 渲染写入的完整原理、关键命令与仓库内的配套参考文件能够亲手为一次 Warp 版本发布起草高质量的 GitHub Release Notes。一、技能定位它解决什么问题Warp 的变更记录流程在 design/towncrier-changelog-fragments.md 中有明确设计贡献者在changelog/目录下添加小型 fragment 文件而非直接编辑CHANGELOG.md以此避免合并冲突并由 Towncrier 在发布时统一渲染成正式 changelog 章节配置位于 pyproject.toml 的[tool.towncrier]段。warp-release-notes技能在此基础上再进一步它不止生成 changelog而是起草面向 GitHub 用户的 Release Notes 正文。核心特征输入是一个位置参数分支名按upstream/name→origin/name→ 本地分支依次解析、标签如v1.13.0或省略参数时默认取HEAD版本字符串取自解析出的 head 处的VERSION.md当前仓库为1.18.0.dev3或直接从 tag 名解析自动区分feature releasepatch 0完整笔记与bugfix releasepatch 0精简笔记输出为单一 Markdown 报告默认写入secret gist当gh可用且已认证时否则落到本地 Markdown 文件。输出物命名规则固定目的地文件名说明Secret gistwarp-version-string-release-notes.md稳定文件名 稳定描述Warp version-string Release Notes Draft后续对同一版本重跑会就地修订同一 gist历史版本保留在 gist 的 git 历史中本地文件warp-version-string-release-notes-YYYY-MM-DD.md带日期、面向用户不会自动提交由发布经理审阅、编辑后复制进 GitHub 发布表单这套技能与仓库的 Towncrier 基建是配套关系changelog/README.md定义了 fragment 的命名、分类与预览方式pyproject.toml的[tool.towncrier]定义了渲染配置而本技能负责在发布那一刻把片段变成「人读得进去、用户能直接上手」的发布说明。二、Phase 1 —— 解析目标与上一个发布版本Phase 1 的目标是确定三个事实head 引用、目标版本号、用于 diff 的上一发布标签。1. 解析 head 引用无参数时 head HEAD有参数时按下述顺序尝试用git rev-parse --verify验证取第一个解析成功的候选upstream/arg → origin/arg → arg本地分支或 tag同时记录符号引用symbolic ref与解析出的完整 SHA。若全部解析失败必须中止并展示候选列表不得静默回退到HEAD。2. 读取版本字符串如果参数是一个匹配vX.Y.Z...的 tag直接从 tag 解析去掉前导v否则从 head 处的VERSION.md读取git show head-ref:VERSION.md去掉空白即原始版本字符串例如1.13.0rc3、1.13.0、1.13.1。3. 解析 (major, minor, patch) 并丢弃预发布后缀从版本号的数字部分解析出三元组丢弃rc1、dev0、.post1等预发布/后发布后缀。发布说明面向最终发布的版本编写因此1.13.0rc3的目标版本是1.13.0。4. 分类发布类型patch 0→feature release完整笔记patch 0→bugfix release精简笔记。5. 确定上一个发布标签diff 基准对解析出的三元组做整数运算Feature releaseX.Y.0取最高的vX.Y-1.*标签若minor 0回退到最高的vX-1.*git tag --list vmajor.minor-1.* --sort-v:refnameBugfix releaseX.Y.ZZ 0取最高的vX.Y.Z且Z Zgit tag --list vmajor.minor.* --sort-v:refname6. 探测 head 上是否已有 tag若git tag --points-at head-ref返回与目标版本匹配的 tag如v1.13.0说明标签已存在但 GitHub release 尚未发布需要在确认消息中注明此时 CHANGELOG 链接可以直接使用该 tag。7. 统计范围内的 commit 数含 cherry-pick 过滤使用与贡献者辅助工具相同的 cherry-pick 过滤范围保证展示给用户的范围与实际待分析的工作一致git log --no-merges --oneline --cherry-pick --right-only prev-tag...head-ref | wc -l注意...对称差与--cherry-pick --right-only组合它会丢弃 patch-id 与上一发布等价的 commit。当上一标签位于 bugfix 分支而非 head 的祖先时这一点至关重要——不做过滤提案可能多报几百个 commit误导用户确认一个错误的范围。若过滤后为 0中止。8. 探测 gh 并查找匹配的 gistgh --version gh auth status任一失败则强制目的地为local并跳过后续步骤否则执行gh gist list --limit 1000过滤出描述与Warp version-string Release Notes Draft完全一致的行记录匹配的 gist ID 与数量0 / 1 / N ≥ 2供 Phase 2 使用。三、Phase 2 —— 与用户确认范围与输出目的地Phase 2 是强制暂停点打印单一提案块后必须等待用户明确确认不得直接进入 Phase 3。提案块以范围行开头Draftingfeature|bugfixrelease notes for Warp .Head:head-refshort-sha(tagtagexists at this SHA)Previous release:prev-tagshort-shaCommits in range:N随后按当前gh/ 匹配状态追加输出块共四种分支gh不可用输出到本地文件ghnot available请确认或指定其他 refgh可用、0 个匹配(a) 新建 secret gist [默认](b) 本地文件gh可用、1 个匹配(a) 就地修订既有 gisturl[默认](b) 新建 secret gist(c) 本地文件gh可用、N 个匹配N ≥ 2列出多个共享稳定标题的 gist含 URL 与更新时间(a) 按编号修订(b) 新建(c) 本地文件。将用户回复翻译为一个目的地 tokenlocal、new-gist或revise-gist:id。字母(a)/(b)/(c)在提示中按位置对应N 匹配分支下数字回复如 revise 2从列表中挑选。若回复中给出新 ref则重新执行 Phase 1。四、Phase 3 —— 收集输入3a —— 当前发布视图先从选定 ref而非调用方工作区读取片段git show head-ref:changelog/README.md git ls-tree -r --name-only head-ref -- changelog排除changelog/README.md记录每个 fragment 的路径、标识符、分类、可选计数器与完整内容。然后选择唯一权威的当前发布视图若 Phase 1 在head-ref找到了匹配目标版本的 tag则直接提取该 tag 的CHANGELOG.md中## [target-version]章节——其顺序是最终且权威的不得重建、排序或重写否则在临时 detached worktree 中用固定的 Towncrier 版本渲染所选 ref 的片段notes_worktree$(mktemp -d) git worktree add --detach $notes_worktree head-ref trap git worktree remove --force $notes_worktree 2/dev/null || true EXIT draft_status0 (cd $notes_worktree uvx --from towncrier25.8.0 towncrier build \ --draft --version target-version --date $(date %F)) || draft_status$? git worktree remove --force $notes_worktree trap - EXIT test $draft_status -eq 0只提取草稿中的## [target-version]章节当没有片段时不得回退到CHANGELOG.md中已发布的章节。随后按### Added / Removed / Deprecated / Changed / Fixed / Documentation收集 bullet为每条记录完整原文、所属章节、GH 引用、可用的源 fragment 路径、experimental 标记与 breaking 标记。另外单独读取head-ref:CHANGELOG.md作为历史发布记录含弃用查询它不是待处理源。3b —— commit 列表与贡献者归属先将skill-dir解析为当前加载的SKILL.md所在目录例如repo/.claude/skills/warp-release-notes或repo/.codex/skills/warp-release-notes不硬编码.claude或.codex。为贡献者归属构造临时 changelog 视图已打 tag 的发布直接用 tag 的完整CHANGELOG.md未打 tag 的发布把 3a 渲染出的目标章节前置到head-ref的历史CHANGELOG.md之前# Tagged release: git show target-tag:CHANGELOG.md /tmp/warp-version-string-changelog.md # Untagged release (rendered_release_section was captured in 3a): { printf %s\n\n $rendered_release_section; \ git show head-ref:CHANGELOG.md; \ |} /tmp/warp-version-string-changelog.md uv run skill-dir/scripts/list_contributors.py \ --base prev-tag \ --head head-ref \ --changelog /tmp/warp-version-string-changelog.md \ --target-version target-version脚本运行完后删除/tmp/warp-version-string-changelog.md。该脚本见 .codex/skills/warp-release-notes/scripts/list_contributors.py是纯标准库、确定性实现输出 JSONcommits[]包含来自 commit message 的 GH 引用、数字 fragment 文件名、历史CHANGELOG.md新增contributors[]包含commit_count、gh_login、classification、pr_summary、changelog_sections、already_shipped、prior_commit_count、is_first_time_contributor、nvidia_low_commit_count。默认运行两道健壮性过滤cherry-pick 过滤丢弃 patch-id 出现在prev-tag中的 commit常见于修复先落入 bugfix 分支再合入 main 的场景与CHANGELOG 章节归属设置already_shipped。Phase 5d 只自动渲染classification external且already_shipped False的贡献者nvidia_low_commit_count与is_first_time_contributor两个标志用于在 Phase 6 的聊天摘要中呈交给人工决策不直接进入渲染出的 Acknowledgments 章节。3c —— 过去版本基调校准可选为校准语气可用gh release view tag --repo NVIDIA/warp --json body --jq .body获取一次同类型近期发布的正文。镜像结构与措辞习惯不复制内容。五、Phase 4 —— 规划分组与调查实现仅 feature releaseBugfix release 跳过 Phase 4 直接进入 Phase 5在 5a 中加一句介绍即可。动笔前需先阅读 references/style-rules.md、references/feature-investigation.md 与 references/feature-release-template.md。识别主打特性lead feature本次发布最激动人心的能力在## New features顶部拥有独立的### …块并配代码示例。优先选择「解锁此前不可能的工作流」的项新产物、新文件格式、跨语言边界而非新参数。尊重用户调用时指定的主打项规划主题分组把其余### Added/### Changed条目按「用户用它做什么」归入 3–6 个主题。常见形状Tile programming enhancements、JAX integration、warp.femenhancements、Compilation and tooling、Performance improvements、Language enhancements、New examples按影响力排序主打特性在前主题按用户影响力排## Bug fixes靠后若无值得重点突出的修复则省略标记实验性条目3a 中带**Experimental**标记的 bullet 在其### …标题下加 [!IMPORTANT]提示块调查实现中的注意事项、产物与仓库内示例把feature-investigation.md的协议应用到主打特性与每个计划书写的### …块。该协议揭示 (a) 实现中埋藏的 not yet supported / TODO 限制(b) 明显文件之外的磁盘/线产物sidecar 目录、计算架构锁定、版本元数据(c) 可链接的仓库内示例warp/examples/**、warp/tests/**(d) 跨语言需求任何跨越 Python ↔ C ↔ JAX 的特性每一侧都要有代码片段不能只给 Python。跳过这步写出来的就是「看起来像发布公告」而不是「让我能上手用」。调查协议本身feature-investigation.md要求把符号解析到真实源文件Python 作用域 API 经warp/__init__.py追踪到warp/_src/下的真实模块kernel 内建函数在warp/_src/builtins.py中搜add_builtin(name, ...)注册C / 原生代码在warp/native/如warp/native/apic.cu、warp/native/mesh.cu示例与测试用warp/examples/**、warp/tests/**glob。引用任何 docstring 中的 Equivalent to、See also 前必须验证符号真实存在且可被用户调用——例如曾经有 docstring 引用了从未注册为 Python 内建的wp.tensordot照搬就会虚构公共符号。六、Phase 5 —— 起草各章节5a —— 开头段落正文开头用 2–3 句点明发布形态。以「解锁的能力」开头而不是 API 名。Feature release 的开头先点名主打特性再带 1–2 个支撑主题。Bugfix release 的开头只有一句Warp vversion is a bugfix release following vprev.加 changelog 指针。5b —— 章节主体填充 references/feature-release-template.mdfeature release或 references/bugfix-release-template.mdbugfix release两个模板都内嵌了逐章节指令。关键规则代码示例是默认项每个描述新公共 API 或行为变更的### …块都要附带可运行的 Python 片段除非只是单参数整理。片段不得调用wp.init()Warp 隐式初始化Breaking change 用 before/after 片段不用散文片段含print(...)时用uv run /tmp/release_notes_example_name.py实际运行嵌入真实捕获的输出单行输出渲染为行尾# comment多行或结构化输出放在 Python 块之后的独立 text 块中当输出本身就是卖点时——如内存追踪器、诊断、dtype 提升——必须如此提示信息一律用 [!NOTE]/ [!IMPORTANT]/ [!CAUTION]等 GFM admonition禁止自造的**Note:**或引用加粗形式style-rules.md 中列出了完整对照与反例。Bugfix 模板的主体是## Highlights3–6 条加粗前缀的 bullet按类别聚合相关修复如 Tile Correctness、Silent Correctness Bugs、Type System and Tooling、CUDA Graphs、Code Generation、Build and Packaging 等每条 1–3 句并带(#NNNN)引用——不要把每个 changelog bullet 都枚举成一条 highlight。5c —— Announcements该章节在 feature 与 bugfix 发布中都可能出现弃用信息会跨发布延续直到真正移除。它只宣布本发布中的变化移除、弃用、平台支持变化、发布节奏变化不复述未变的政策。若某子节本发布无实际变化则删除该子节若无任何子节适用则删除整个## Announcements。素材来源六处渲染后的当前### Removed每条都是### Removals in this release的候选 bullet语气规则见 style-rules.md 的 Tone for removals and deprecations中立的迁移步骤不指责之前的弃用警告渲染后的当前### Deprecated每条都是### Upcoming removals的候选 bullet。只有主来源承诺了具体移除版本条目文本、运行时DeprecationWarning字符串、docstring、设计文档或维护者声明才可写明否则用中性表述 will be removed in a future feature release per the standard deprecation timeline此前发布中明确点名本发布为移除版本的### Deprecated这些弃用现已落地升格到### Removals in this release平台支持变化仅当本发布真的变了才写。直接对比 head ref 与上一 tag 的源码差异Python 支持看pyproject.toml的requires-python与Programming Language :: Python :: 3.Xclassifiers 及.python-versionCUDA Toolkit 看warp/_src/build_dll.py的MIN_CTK_VERSION与build_lib.py的CTK_*常量OS/arch 看pyproject.toml的 cibuildwheel 配置与构建脚本中的manylinux_*/macosx_*约束。无变化则删除子节有变化只陈述变化本身如 Python 3.9 is no longer supported不陈述未变的基线发布节奏变化仅当实际变化且使用祈愿语气Warp aims to publish a feature release every month而非陈述语气CHANGELOG 之外、由用户负责的事实分配器政策变化、安全公告、构建尚未强制执行的计划性支持变化在聊天摘要中呈交候选由用户确认或删除。5d —— Acknowledgments使用 Phase 3b 的contributors[]过滤already_shipped False已感谢过的在聊天摘要中呈现。自动渲染仅限classification externalgh_login非空- gh-login for one-line summary (#NNNN).gh_login为空无gh或无法关联 GitHub 用户不渲染None/null渲染- name for one-line summary (#NNNN).并在聊天摘要中呈交供发布经理补全 handle 或删除无匹配 CHANGELOG bullet 时省略尾部(#NNNN)。过滤后自动渲染列表为空时在章节标题下渲染No external contributions in this release.。**呈交人工决策不自动渲染致谢行**两类nvidia_low_commit_count True被归类为 NVIDIA、但本范围内 commit 少且历史 commit 也少的贡献者可能不在 Warp 团队内发布经理可考虑像外部贡献者一样致谢。展示姓名、GitHub 登录若知、commit 数、历史 commit 数与pr_summary中的贡献主题is_first_time_contributor True无论分类diff 基准之前在仓库中没有任何 commit。发布经理可考虑加 Welcome our first-time contributors: 提示。两组标志可能重叠首次贡献的 NVIDIA 员工同时命中两者每位贡献者只呈交一次同时命中时注明两个标志。5e —— 交给用户前的自审把草稿交给发布经理前重读 references/style-rules.mdfeature release 还要读feature-investigation.mdbugfix 跳过 Phase 4 也可跳过其规则并逐条核对。每一条未应用的规则都是发布经理本可省去的一轮迭代。七、Phase 6 —— 渲染并写入所选目的地在所选模板中填充每个{{PLACEHOLDER}}应用 style-rules.md 的核心约定用#NNNN而非GH-NNNN发布说明发布在同一个 GitHub 仓库#NNNN会被 GitHub 自动解析为可点击链接、experimental 用 [!IMPORTANT]、禁用破折号em dash、不使用技能内部术语、专有名词正确大写。目的地已在 Phase 2 选定。文件名约定本地文件在$(pwd)warp-version-string-release-notes-today.md——带日期、面向用户Gist 文件gist 内部warp-version-string-release-notes.md——不带日期稳定名使后续运行就地修订同一 gist。稳定 gist 描述新建 gist 时使用也是 Phase 1.8 的匹配键Warp version-string Release Notes Draft三种写入方式local用 Write 工具写入$(pwd)/local-filenamenew-gist先写/tmp/gist-filename执行gh gist create --desc stable-desc /tmp/gist-filename并从 stdout 捕获 URL随后删除临时文件revise-gist:id先写/tmp/gist-filename与既有 gist 相同的稳定名执行gh gist edit id --filename gist-filename /tmp/gist-filename。--filename选择 gist内部要替换的文件尾部本地路径提供新内容——不传--filename时gh会把本地路径当作 gist 侧文件名选择器找不到后落入交互式编辑器。不要传--desc保持描述稳定正是下一次运行能再次匹配该 gist 的原因。旧版本自动保留在 gist 的 git 历史中。绝不传--public绝不把草稿投递到用户未选择的目的地。结束后打印一行聊天摘要输出路径/URL 要点计数特性数、公告数、外部贡献者数并按需追加revise-gist时说明revised in place; prior versions kept in gist git historyalready_shipped True的条目列出 Already-shipped contributors skipped: user1 (sections[1.12.1]), ... 供抽查渲染致谢中gh_login为空的列出 Unresolved GitHub handles (rendered with name only): ( ), ...is_first_time_contributor True的列出 First-time contributors (consider a shoutout): user1 (1 commit, ), ...并注明分类nvidia_low_commit_count True的排除已计入首次贡献者列出 NVIDIA contributors with low commit count (likely outside Warp team, consider acknowledging): ...。对revise-gist:id目的地提醒发布经理旧版本保留在 gist 的 git 历史中可跨迭代 diff。八、失败模式与保护技能明确列出九类失败场景及对应的中止策略保证绝不产出误导性草稿失败场景处理参数无法解析打印候选列表upstream/arg、origin/arg、arg并中止不静默回退 HEADhead 处VERSION.md缺失或不可解析中止并显示原始文件内容找不到上一个标签feature release无更早 minor仅存在于v1.0.0等情形bugfix无vX.Y.Z且Z Z。中止并要求用户手动指定基准tag 中缺少目标章节中止该 tag 不含预期的## [target-version]章节打 tag 前没有待处理片段中止不得用最新的历史发布章节替代Towncrier draft 失败展示其输出并中止不得手工拼装发布章节gh不可用list_contributors.py退化为仅按邮箱分类只有nvidia.com记为内部用 noreply/个人地址提交的私有成员 NVIDIA 员工会被误判为external需在聊天摘要中注明过滤后 commit 数为 0中止未获用户确认Phase 2 强制等待不进入 Phase 3九、正则与解析规则内联参考技能内置一组精确正则覆盖版本、片段、章节与标记的解析用途正则说明GH 引用\bGH-(\d)从 commit body 提取 issue 号标签模式^v(\d)\.(\d)\.(\d)([a-z0-9.-]*)$尾组捕获rc1、dev0、.post1等片段路径^changelog/(?:\[A-Za-z0-9][A-Za-z0-9-]*|\d)\.(added\|removed\|deprecated\|changed\|fixed\|documentation)(?:\.\d)?\.md$与changelog/README.md的命名规则严格对应目标章节头^## \[target-version\]可选尾随日期CHANGELOG 子章节头^### (Added\|Removed\|Deprecated\|Changed\|Fixed\|Documentation)六分类固定顺序Experimental 标记\*\*Experimental\*\*:?加粗、可选尾随冒号Breaking 标记字面量**Breaking:**触发 before/after 片段noreply 邮箱登录名^\d\([^])users\.noreply\.github\.com$组 1 即 GitHub 用户名这些规则与 pyproject.toml 中[tool.towncrier]的issue_pattern \d、issue_format GH-{issue}及六个[[tool.towncrier.type]]Added / Removed / Deprecated / Changed / Fixed / Documentation顺序即渲染顺序形成闭环也与 changelog/README.md 中对贡献者的指引数字标识符用 issue 号、孤儿标识符用前缀、同名同类用计数器、同文本多 issue 片段合并为一条多链接 bullet一一呼应。十、与仓库配套设施的关系这套技能不是孤岛它与仓库内多个设施协同片段来源changelog/README.md 是 fragment 命名、分类、写作指南、本地预览命令与发布流程的权威文档贡献者按它添加片段发布流程本身记录在 design/towncrier-changelog-fragments.md迁移、发布分支流程、changelog-only 同步 PR渲染配置pyproject.toml 的[tool.towncrier]段定义directory changelog、filename CHANGELOG.md、title_format ## [{version}] - {project_date}ignore []使 draft 构建报告畸形片段名而非静默跳过wrap false避免重排贡献者散文当前发布状态VERSION.md当前1.18.0.dev3与 CHANGELOG.md顶部!-- towncrier release notes start --插入标记之下是## [1.17.0] - 2026-08-31等已发布章节共同决定了下一个目标版本与 diff 基准技能双树镜像.codex/skills/warp-release-notes/与.claude/skills/warp-release-notes/各含同一份SKILL.md、references/五份参考文档与scripts/list_contributors.py技能内容须在两个技能树中都可工作因此skill-dir必须动态解析而非硬编码贡献者脚本实现scripts/list_contributors.py 用git log单次调用自定义格式 --name-onlyASCII Record/Unit Separator 分隔字段枚举base..head的 commit跳过 merge、默认--cherry-pick --right-only再按 references/contributor-attribution.md 的规则分类NVIDIA 邮箱域名*nvidia.com、*exchange.nvidia.com或 NVIDIA GitHub 组织成员gh api /orgs/NVIDIA/members/login返回 204判为nvidia其余为external。注意组织成员接口仅对同为组织成员的调用者返回 204外部调用者即使对真实成员也得到 404——技能假定发布经理是 NVIDIA 组织成员发布前人工复核致谢名单无论如何都必要贡献入口CONTRIBUTING.md 指引贡献者添加 changelog fragment与技能读取片段的流程相接。结语从片段到可发布的 GitHub Release Notes纵观六个阶段warp-release-notes技能把「发布说明」这个通常靠人工拼凑的环节变成了一条可重复、可审计的流水线Phase 1 用整数版本运算与 cherry-pick 过滤确定真实 diff 范围Phase 2 强制人机确认防止误导性草稿Phase 3 从 ref 而非工作区取数保证可复现Phase 4–5 以「解锁能力」优先、代码示例默认、before/after 承载破坏性变更的方式组织内容Phase 6 则把成果安全投递到 gist 或本地文件。配合仓库既有的 Towncrier 基建changelog/README.md、pyproject.toml配置、CHANGELOG.md历史与.claude/.codex双技能树镜像Warp 的每次发布都能产出一份「让用户看完就能上手」的高质量发布说明。【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Warp 发布说明自动起草全流程：基于 Towncrier 片段的 GitHub Release Notes 生成指南
Warp 发布说明自动起草全流程基于 Towncrier 片段的 GitHub Release Notes 生成指南【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp本文以 NVIDIA WarpGPU 加速的 Python 仿真/机器人/机器学习框架仓库中的.codex/skills/warp-release-notes技能为蓝本系统讲解如何从 Towncrier changelog 片段fragment或已打 tag 的最终 CHANGELOG 自动生成 GitHub 发布说明Release Notes草稿。技能负责自动识别 feature / bugfix 发布类型、解析上一个版本标签作为 diff 基准、聚合片段与贡献者归属并产出可直接编辑发布的 Markdown 文档。读完本文你将掌握这套六阶段流水线解析目标版本 → 与用户确认 → 收集输入 → 规划分组 → 起草章节 → 渲染写入的完整原理、关键命令与仓库内的配套参考文件能够亲手为一次 Warp 版本发布起草高质量的 GitHub Release Notes。一、技能定位它解决什么问题Warp 的变更记录流程在 design/towncrier-changelog-fragments.md 中有明确设计贡献者在changelog/目录下添加小型 fragment 文件而非直接编辑CHANGELOG.md以此避免合并冲突并由 Towncrier 在发布时统一渲染成正式 changelog 章节配置位于 pyproject.toml 的[tool.towncrier]段。warp-release-notes技能在此基础上再进一步它不止生成 changelog而是起草面向 GitHub 用户的 Release Notes 正文。核心特征输入是一个位置参数分支名按upstream/name→origin/name→ 本地分支依次解析、标签如v1.13.0或省略参数时默认取HEAD版本字符串取自解析出的 head 处的VERSION.md当前仓库为1.18.0.dev3或直接从 tag 名解析自动区分feature releasepatch 0完整笔记与bugfix releasepatch 0精简笔记输出为单一 Markdown 报告默认写入secret gist当gh可用且已认证时否则落到本地 Markdown 文件。输出物命名规则固定目的地文件名说明Secret gistwarp-version-string-release-notes.md稳定文件名 稳定描述Warp version-string Release Notes Draft后续对同一版本重跑会就地修订同一 gist历史版本保留在 gist 的 git 历史中本地文件warp-version-string-release-notes-YYYY-MM-DD.md带日期、面向用户不会自动提交由发布经理审阅、编辑后复制进 GitHub 发布表单这套技能与仓库的 Towncrier 基建是配套关系changelog/README.md定义了 fragment 的命名、分类与预览方式pyproject.toml的[tool.towncrier]定义了渲染配置而本技能负责在发布那一刻把片段变成「人读得进去、用户能直接上手」的发布说明。二、Phase 1 —— 解析目标与上一个发布版本Phase 1 的目标是确定三个事实head 引用、目标版本号、用于 diff 的上一发布标签。1. 解析 head 引用无参数时 head HEAD有参数时按下述顺序尝试用git rev-parse --verify验证取第一个解析成功的候选upstream/arg → origin/arg → arg本地分支或 tag同时记录符号引用symbolic ref与解析出的完整 SHA。若全部解析失败必须中止并展示候选列表不得静默回退到HEAD。2. 读取版本字符串如果参数是一个匹配vX.Y.Z...的 tag直接从 tag 解析去掉前导v否则从 head 处的VERSION.md读取git show head-ref:VERSION.md去掉空白即原始版本字符串例如1.13.0rc3、1.13.0、1.13.1。3. 解析 (major, minor, patch) 并丢弃预发布后缀从版本号的数字部分解析出三元组丢弃rc1、dev0、.post1等预发布/后发布后缀。发布说明面向最终发布的版本编写因此1.13.0rc3的目标版本是1.13.0。4. 分类发布类型patch 0→feature release完整笔记patch 0→bugfix release精简笔记。5. 确定上一个发布标签diff 基准对解析出的三元组做整数运算Feature releaseX.Y.0取最高的vX.Y-1.*标签若minor 0回退到最高的vX-1.*git tag --list vmajor.minor-1.* --sort-v:refnameBugfix releaseX.Y.ZZ 0取最高的vX.Y.Z且Z Zgit tag --list vmajor.minor.* --sort-v:refname6. 探测 head 上是否已有 tag若git tag --points-at head-ref返回与目标版本匹配的 tag如v1.13.0说明标签已存在但 GitHub release 尚未发布需要在确认消息中注明此时 CHANGELOG 链接可以直接使用该 tag。7. 统计范围内的 commit 数含 cherry-pick 过滤使用与贡献者辅助工具相同的 cherry-pick 过滤范围保证展示给用户的范围与实际待分析的工作一致git log --no-merges --oneline --cherry-pick --right-only prev-tag...head-ref | wc -l注意...对称差与--cherry-pick --right-only组合它会丢弃 patch-id 与上一发布等价的 commit。当上一标签位于 bugfix 分支而非 head 的祖先时这一点至关重要——不做过滤提案可能多报几百个 commit误导用户确认一个错误的范围。若过滤后为 0中止。8. 探测 gh 并查找匹配的 gistgh --version gh auth status任一失败则强制目的地为local并跳过后续步骤否则执行gh gist list --limit 1000过滤出描述与Warp version-string Release Notes Draft完全一致的行记录匹配的 gist ID 与数量0 / 1 / N ≥ 2供 Phase 2 使用。三、Phase 2 —— 与用户确认范围与输出目的地Phase 2 是强制暂停点打印单一提案块后必须等待用户明确确认不得直接进入 Phase 3。提案块以范围行开头Draftingfeature|bugfixrelease notes for Warp .Head:head-refshort-sha(tagtagexists at this SHA)Previous release:prev-tagshort-shaCommits in range:N随后按当前gh/ 匹配状态追加输出块共四种分支gh不可用输出到本地文件ghnot available请确认或指定其他 refgh可用、0 个匹配(a) 新建 secret gist [默认](b) 本地文件gh可用、1 个匹配(a) 就地修订既有 gisturl[默认](b) 新建 secret gist(c) 本地文件gh可用、N 个匹配N ≥ 2列出多个共享稳定标题的 gist含 URL 与更新时间(a) 按编号修订(b) 新建(c) 本地文件。将用户回复翻译为一个目的地 tokenlocal、new-gist或revise-gist:id。字母(a)/(b)/(c)在提示中按位置对应N 匹配分支下数字回复如 revise 2从列表中挑选。若回复中给出新 ref则重新执行 Phase 1。四、Phase 3 —— 收集输入3a —— 当前发布视图先从选定 ref而非调用方工作区读取片段git show head-ref:changelog/README.md git ls-tree -r --name-only head-ref -- changelog排除changelog/README.md记录每个 fragment 的路径、标识符、分类、可选计数器与完整内容。然后选择唯一权威的当前发布视图若 Phase 1 在head-ref找到了匹配目标版本的 tag则直接提取该 tag 的CHANGELOG.md中## [target-version]章节——其顺序是最终且权威的不得重建、排序或重写否则在临时 detached worktree 中用固定的 Towncrier 版本渲染所选 ref 的片段notes_worktree$(mktemp -d) git worktree add --detach $notes_worktree head-ref trap git worktree remove --force $notes_worktree 2/dev/null || true EXIT draft_status0 (cd $notes_worktree uvx --from towncrier25.8.0 towncrier build \ --draft --version target-version --date $(date %F)) || draft_status$? git worktree remove --force $notes_worktree trap - EXIT test $draft_status -eq 0只提取草稿中的## [target-version]章节当没有片段时不得回退到CHANGELOG.md中已发布的章节。随后按### Added / Removed / Deprecated / Changed / Fixed / Documentation收集 bullet为每条记录完整原文、所属章节、GH 引用、可用的源 fragment 路径、experimental 标记与 breaking 标记。另外单独读取head-ref:CHANGELOG.md作为历史发布记录含弃用查询它不是待处理源。3b —— commit 列表与贡献者归属先将skill-dir解析为当前加载的SKILL.md所在目录例如repo/.claude/skills/warp-release-notes或repo/.codex/skills/warp-release-notes不硬编码.claude或.codex。为贡献者归属构造临时 changelog 视图已打 tag 的发布直接用 tag 的完整CHANGELOG.md未打 tag 的发布把 3a 渲染出的目标章节前置到head-ref的历史CHANGELOG.md之前# Tagged release: git show target-tag:CHANGELOG.md /tmp/warp-version-string-changelog.md # Untagged release (rendered_release_section was captured in 3a): { printf %s\n\n $rendered_release_section; \ git show head-ref:CHANGELOG.md; \ |} /tmp/warp-version-string-changelog.md uv run skill-dir/scripts/list_contributors.py \ --base prev-tag \ --head head-ref \ --changelog /tmp/warp-version-string-changelog.md \ --target-version target-version脚本运行完后删除/tmp/warp-version-string-changelog.md。该脚本见 .codex/skills/warp-release-notes/scripts/list_contributors.py是纯标准库、确定性实现输出 JSONcommits[]包含来自 commit message 的 GH 引用、数字 fragment 文件名、历史CHANGELOG.md新增contributors[]包含commit_count、gh_login、classification、pr_summary、changelog_sections、already_shipped、prior_commit_count、is_first_time_contributor、nvidia_low_commit_count。默认运行两道健壮性过滤cherry-pick 过滤丢弃 patch-id 出现在prev-tag中的 commit常见于修复先落入 bugfix 分支再合入 main 的场景与CHANGELOG 章节归属设置already_shipped。Phase 5d 只自动渲染classification external且already_shipped False的贡献者nvidia_low_commit_count与is_first_time_contributor两个标志用于在 Phase 6 的聊天摘要中呈交给人工决策不直接进入渲染出的 Acknowledgments 章节。3c —— 过去版本基调校准可选为校准语气可用gh release view tag --repo NVIDIA/warp --json body --jq .body获取一次同类型近期发布的正文。镜像结构与措辞习惯不复制内容。五、Phase 4 —— 规划分组与调查实现仅 feature releaseBugfix release 跳过 Phase 4 直接进入 Phase 5在 5a 中加一句介绍即可。动笔前需先阅读 references/style-rules.md、references/feature-investigation.md 与 references/feature-release-template.md。识别主打特性lead feature本次发布最激动人心的能力在## New features顶部拥有独立的### …块并配代码示例。优先选择「解锁此前不可能的工作流」的项新产物、新文件格式、跨语言边界而非新参数。尊重用户调用时指定的主打项规划主题分组把其余### Added/### Changed条目按「用户用它做什么」归入 3–6 个主题。常见形状Tile programming enhancements、JAX integration、warp.femenhancements、Compilation and tooling、Performance improvements、Language enhancements、New examples按影响力排序主打特性在前主题按用户影响力排## Bug fixes靠后若无值得重点突出的修复则省略标记实验性条目3a 中带**Experimental**标记的 bullet 在其### …标题下加 [!IMPORTANT]提示块调查实现中的注意事项、产物与仓库内示例把feature-investigation.md的协议应用到主打特性与每个计划书写的### …块。该协议揭示 (a) 实现中埋藏的 not yet supported / TODO 限制(b) 明显文件之外的磁盘/线产物sidecar 目录、计算架构锁定、版本元数据(c) 可链接的仓库内示例warp/examples/**、warp/tests/**(d) 跨语言需求任何跨越 Python ↔ C ↔ JAX 的特性每一侧都要有代码片段不能只给 Python。跳过这步写出来的就是「看起来像发布公告」而不是「让我能上手用」。调查协议本身feature-investigation.md要求把符号解析到真实源文件Python 作用域 API 经warp/__init__.py追踪到warp/_src/下的真实模块kernel 内建函数在warp/_src/builtins.py中搜add_builtin(name, ...)注册C / 原生代码在warp/native/如warp/native/apic.cu、warp/native/mesh.cu示例与测试用warp/examples/**、warp/tests/**glob。引用任何 docstring 中的 Equivalent to、See also 前必须验证符号真实存在且可被用户调用——例如曾经有 docstring 引用了从未注册为 Python 内建的wp.tensordot照搬就会虚构公共符号。六、Phase 5 —— 起草各章节5a —— 开头段落正文开头用 2–3 句点明发布形态。以「解锁的能力」开头而不是 API 名。Feature release 的开头先点名主打特性再带 1–2 个支撑主题。Bugfix release 的开头只有一句Warp vversion is a bugfix release following vprev.加 changelog 指针。5b —— 章节主体填充 references/feature-release-template.mdfeature release或 references/bugfix-release-template.mdbugfix release两个模板都内嵌了逐章节指令。关键规则代码示例是默认项每个描述新公共 API 或行为变更的### …块都要附带可运行的 Python 片段除非只是单参数整理。片段不得调用wp.init()Warp 隐式初始化Breaking change 用 before/after 片段不用散文片段含print(...)时用uv run /tmp/release_notes_example_name.py实际运行嵌入真实捕获的输出单行输出渲染为行尾# comment多行或结构化输出放在 Python 块之后的独立 text 块中当输出本身就是卖点时——如内存追踪器、诊断、dtype 提升——必须如此提示信息一律用 [!NOTE]/ [!IMPORTANT]/ [!CAUTION]等 GFM admonition禁止自造的**Note:**或引用加粗形式style-rules.md 中列出了完整对照与反例。Bugfix 模板的主体是## Highlights3–6 条加粗前缀的 bullet按类别聚合相关修复如 Tile Correctness、Silent Correctness Bugs、Type System and Tooling、CUDA Graphs、Code Generation、Build and Packaging 等每条 1–3 句并带(#NNNN)引用——不要把每个 changelog bullet 都枚举成一条 highlight。5c —— Announcements该章节在 feature 与 bugfix 发布中都可能出现弃用信息会跨发布延续直到真正移除。它只宣布本发布中的变化移除、弃用、平台支持变化、发布节奏变化不复述未变的政策。若某子节本发布无实际变化则删除该子节若无任何子节适用则删除整个## Announcements。素材来源六处渲染后的当前### Removed每条都是### Removals in this release的候选 bullet语气规则见 style-rules.md 的 Tone for removals and deprecations中立的迁移步骤不指责之前的弃用警告渲染后的当前### Deprecated每条都是### Upcoming removals的候选 bullet。只有主来源承诺了具体移除版本条目文本、运行时DeprecationWarning字符串、docstring、设计文档或维护者声明才可写明否则用中性表述 will be removed in a future feature release per the standard deprecation timeline此前发布中明确点名本发布为移除版本的### Deprecated这些弃用现已落地升格到### Removals in this release平台支持变化仅当本发布真的变了才写。直接对比 head ref 与上一 tag 的源码差异Python 支持看pyproject.toml的requires-python与Programming Language :: Python :: 3.Xclassifiers 及.python-versionCUDA Toolkit 看warp/_src/build_dll.py的MIN_CTK_VERSION与build_lib.py的CTK_*常量OS/arch 看pyproject.toml的 cibuildwheel 配置与构建脚本中的manylinux_*/macosx_*约束。无变化则删除子节有变化只陈述变化本身如 Python 3.9 is no longer supported不陈述未变的基线发布节奏变化仅当实际变化且使用祈愿语气Warp aims to publish a feature release every month而非陈述语气CHANGELOG 之外、由用户负责的事实分配器政策变化、安全公告、构建尚未强制执行的计划性支持变化在聊天摘要中呈交候选由用户确认或删除。5d —— Acknowledgments使用 Phase 3b 的contributors[]过滤already_shipped False已感谢过的在聊天摘要中呈现。自动渲染仅限classification externalgh_login非空- gh-login for one-line summary (#NNNN).gh_login为空无gh或无法关联 GitHub 用户不渲染None/null渲染- name for one-line summary (#NNNN).并在聊天摘要中呈交供发布经理补全 handle 或删除无匹配 CHANGELOG bullet 时省略尾部(#NNNN)。过滤后自动渲染列表为空时在章节标题下渲染No external contributions in this release.。**呈交人工决策不自动渲染致谢行**两类nvidia_low_commit_count True被归类为 NVIDIA、但本范围内 commit 少且历史 commit 也少的贡献者可能不在 Warp 团队内发布经理可考虑像外部贡献者一样致谢。展示姓名、GitHub 登录若知、commit 数、历史 commit 数与pr_summary中的贡献主题is_first_time_contributor True无论分类diff 基准之前在仓库中没有任何 commit。发布经理可考虑加 Welcome our first-time contributors: 提示。两组标志可能重叠首次贡献的 NVIDIA 员工同时命中两者每位贡献者只呈交一次同时命中时注明两个标志。5e —— 交给用户前的自审把草稿交给发布经理前重读 references/style-rules.mdfeature release 还要读feature-investigation.mdbugfix 跳过 Phase 4 也可跳过其规则并逐条核对。每一条未应用的规则都是发布经理本可省去的一轮迭代。七、Phase 6 —— 渲染并写入所选目的地在所选模板中填充每个{{PLACEHOLDER}}应用 style-rules.md 的核心约定用#NNNN而非GH-NNNN发布说明发布在同一个 GitHub 仓库#NNNN会被 GitHub 自动解析为可点击链接、experimental 用 [!IMPORTANT]、禁用破折号em dash、不使用技能内部术语、专有名词正确大写。目的地已在 Phase 2 选定。文件名约定本地文件在$(pwd)warp-version-string-release-notes-today.md——带日期、面向用户Gist 文件gist 内部warp-version-string-release-notes.md——不带日期稳定名使后续运行就地修订同一 gist。稳定 gist 描述新建 gist 时使用也是 Phase 1.8 的匹配键Warp version-string Release Notes Draft三种写入方式local用 Write 工具写入$(pwd)/local-filenamenew-gist先写/tmp/gist-filename执行gh gist create --desc stable-desc /tmp/gist-filename并从 stdout 捕获 URL随后删除临时文件revise-gist:id先写/tmp/gist-filename与既有 gist 相同的稳定名执行gh gist edit id --filename gist-filename /tmp/gist-filename。--filename选择 gist内部要替换的文件尾部本地路径提供新内容——不传--filename时gh会把本地路径当作 gist 侧文件名选择器找不到后落入交互式编辑器。不要传--desc保持描述稳定正是下一次运行能再次匹配该 gist 的原因。旧版本自动保留在 gist 的 git 历史中。绝不传--public绝不把草稿投递到用户未选择的目的地。结束后打印一行聊天摘要输出路径/URL 要点计数特性数、公告数、外部贡献者数并按需追加revise-gist时说明revised in place; prior versions kept in gist git historyalready_shipped True的条目列出 Already-shipped contributors skipped: user1 (sections[1.12.1]), ... 供抽查渲染致谢中gh_login为空的列出 Unresolved GitHub handles (rendered with name only): ( ), ...is_first_time_contributor True的列出 First-time contributors (consider a shoutout): user1 (1 commit, ), ...并注明分类nvidia_low_commit_count True的排除已计入首次贡献者列出 NVIDIA contributors with low commit count (likely outside Warp team, consider acknowledging): ...。对revise-gist:id目的地提醒发布经理旧版本保留在 gist 的 git 历史中可跨迭代 diff。八、失败模式与保护技能明确列出九类失败场景及对应的中止策略保证绝不产出误导性草稿失败场景处理参数无法解析打印候选列表upstream/arg、origin/arg、arg并中止不静默回退 HEADhead 处VERSION.md缺失或不可解析中止并显示原始文件内容找不到上一个标签feature release无更早 minor仅存在于v1.0.0等情形bugfix无vX.Y.Z且Z Z。中止并要求用户手动指定基准tag 中缺少目标章节中止该 tag 不含预期的## [target-version]章节打 tag 前没有待处理片段中止不得用最新的历史发布章节替代Towncrier draft 失败展示其输出并中止不得手工拼装发布章节gh不可用list_contributors.py退化为仅按邮箱分类只有nvidia.com记为内部用 noreply/个人地址提交的私有成员 NVIDIA 员工会被误判为external需在聊天摘要中注明过滤后 commit 数为 0中止未获用户确认Phase 2 强制等待不进入 Phase 3九、正则与解析规则内联参考技能内置一组精确正则覆盖版本、片段、章节与标记的解析用途正则说明GH 引用\bGH-(\d)从 commit body 提取 issue 号标签模式^v(\d)\.(\d)\.(\d)([a-z0-9.-]*)$尾组捕获rc1、dev0、.post1等片段路径^changelog/(?:\[A-Za-z0-9][A-Za-z0-9-]*|\d)\.(added\|removed\|deprecated\|changed\|fixed\|documentation)(?:\.\d)?\.md$与changelog/README.md的命名规则严格对应目标章节头^## \[target-version\]可选尾随日期CHANGELOG 子章节头^### (Added\|Removed\|Deprecated\|Changed\|Fixed\|Documentation)六分类固定顺序Experimental 标记\*\*Experimental\*\*:?加粗、可选尾随冒号Breaking 标记字面量**Breaking:**触发 before/after 片段noreply 邮箱登录名^\d\([^])users\.noreply\.github\.com$组 1 即 GitHub 用户名这些规则与 pyproject.toml 中[tool.towncrier]的issue_pattern \d、issue_format GH-{issue}及六个[[tool.towncrier.type]]Added / Removed / Deprecated / Changed / Fixed / Documentation顺序即渲染顺序形成闭环也与 changelog/README.md 中对贡献者的指引数字标识符用 issue 号、孤儿标识符用前缀、同名同类用计数器、同文本多 issue 片段合并为一条多链接 bullet一一呼应。十、与仓库配套设施的关系这套技能不是孤岛它与仓库内多个设施协同片段来源changelog/README.md 是 fragment 命名、分类、写作指南、本地预览命令与发布流程的权威文档贡献者按它添加片段发布流程本身记录在 design/towncrier-changelog-fragments.md迁移、发布分支流程、changelog-only 同步 PR渲染配置pyproject.toml 的[tool.towncrier]段定义directory changelog、filename CHANGELOG.md、title_format ## [{version}] - {project_date}ignore []使 draft 构建报告畸形片段名而非静默跳过wrap false避免重排贡献者散文当前发布状态VERSION.md当前1.18.0.dev3与 CHANGELOG.md顶部!-- towncrier release notes start --插入标记之下是## [1.17.0] - 2026-08-31等已发布章节共同决定了下一个目标版本与 diff 基准技能双树镜像.codex/skills/warp-release-notes/与.claude/skills/warp-release-notes/各含同一份SKILL.md、references/五份参考文档与scripts/list_contributors.py技能内容须在两个技能树中都可工作因此skill-dir必须动态解析而非硬编码贡献者脚本实现scripts/list_contributors.py 用git log单次调用自定义格式 --name-onlyASCII Record/Unit Separator 分隔字段枚举base..head的 commit跳过 merge、默认--cherry-pick --right-only再按 references/contributor-attribution.md 的规则分类NVIDIA 邮箱域名*nvidia.com、*exchange.nvidia.com或 NVIDIA GitHub 组织成员gh api /orgs/NVIDIA/members/login返回 204判为nvidia其余为external。注意组织成员接口仅对同为组织成员的调用者返回 204外部调用者即使对真实成员也得到 404——技能假定发布经理是 NVIDIA 组织成员发布前人工复核致谢名单无论如何都必要贡献入口CONTRIBUTING.md 指引贡献者添加 changelog fragment与技能读取片段的流程相接。结语从片段到可发布的 GitHub Release Notes纵观六个阶段warp-release-notes技能把「发布说明」这个通常靠人工拼凑的环节变成了一条可重复、可审计的流水线Phase 1 用整数版本运算与 cherry-pick 过滤确定真实 diff 范围Phase 2 强制人机确认防止误导性草稿Phase 3 从 ref 而非工作区取数保证可复现Phase 4–5 以「解锁能力」优先、代码示例默认、before/after 承载破坏性变更的方式组织内容Phase 6 则把成果安全投递到 gist 或本地文件。配合仓库既有的 Towncrier 基建changelog/README.md、pyproject.toml配置、CHANGELOG.md历史与.claude/.codex双技能树镜像Warp 的每次发布都能产出一份「让用户看完就能上手」的高质量发布说明。【免费下载链接】warpA Python framework for GPU-accelerated simulation, robotics, and machine learning.项目地址: https://gitcode.com/GitHub_Trending/warp/warp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考