uv 发布工程实战editorialize-changelog 提示词如何自动化重写 CHANGELOG【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uvuv 仓库将“重写发布说明”这件事沉淀为一个可被 CI 直接消费的提示词文件 editorialize-changelog.md由发布准备流水线release-prepareworkflow在版本号提升后调用 Codex 对 CHANGELOG.md 的最新版本小节做“编辑化”重写。读完本文你将掌握uv 的 changelog 结构与条目规范、该提示词中每一条编辑规则的设计意图以及 CI 中“LLM 生成 确定性脚本落盘”的完整落地链路这些经验可以直接迁移到你自己的 Rust/Python 项目发布流程中。uv 的 CHANGELOG 结构与“最新发布小节”CHANGELOG.md 采用统一的组织方式文件以# Changelog开头随后每个版本一个小节小节标题是##二级标题内含发布日期和若干###分组。以当前最新版本为例## 0.12.9 Released on 2026-09-01. ### Python ### Enhancements ### Performance ### Bug fixes各小节内是单行 Markdown 列表项每条都带有指向 pull request 的链接例如Add--no-lockedand--no-frozento disable lock modes enabled byUV_LOCKEDandUV_FROZENfor a single invocation (#21408)可以观察到的既有分组命名包括Python、Enhancements、Preview features、Performance、Bug fixes、Other changes。旧版本的历史内容会被归档到 changelogs/ 目录下按大版本拆分的文件中例如 changelogs/0.1.x.md配合 scripts/reverse-changelog.py 在归档时按## \d\.\d\.\d正则切分版本块并反转顺序。“最新发布小节”the newest release section的边界在提示词中有精确定义从第一个##释放标题开始到下一个##标题之前立即结束。这个定义与后续落盘脚本的行为严格对应后文会展开。提示词在整个发布流水线中的位置CONTRIBUTING.md 的 “Releases” 一节说明changelog 条目与版本号提升是自动化的先运行 scripts/release.sh它调用 rooster 更新 changelog、提升 workspace crate 版本、刷新 lockfile 并创建release/x.y.z分支然后“editorialize theCHANGELOG.mdfile to ensure entries are consistently styled”最后提交 pull request。在仓库中这一步已经被 CI 完整自动化。.github/workflows/release-prepare.yml 是一条workflow_dispatch触发的“Prepare release”流水线关键步骤依次为Bump version执行./scripts/release.sh可选--version参数覆盖自动检测Prepare Codex prompt把一行版本上下文与提示词拼成完整 prompt 文件{ printf Release preparation for %s: Rewrite changelog\n\n $(uv version --short) cat agents/prompts/editorialize-changelog.md } $RUNNER_TEMP/editorialize-changelog-prompt.mdRewrite changelog以openai/codex-action运行permission-profile: :read-only只读权限、effort: highprompt 与输出分别写入 runner 临时目录Apply changelog rewriteuv run scripts/update-latest-changelog-section.py CHANGELOG.md $RUNNER_TEMP/changelog-section.md把模型输出落盘Commit changelog rewritegit diff --check后按需提交Rewrite changelog若模型未改动则跳过提交最后推送并创建/复用 PR。CONTRIBUTING.md 还要求若 release 准备检测到新的 workspace crate需将其登记到 crates-policies合并 PR 后运行 release workflow 发布版本标签不带前导v。提示词全文规则逐条解析editorialize-changelog.md 全文约 40 行但信息密度很高可以拆成四个层次任务边界、事实来源、编辑规则、输出契约。任务边界只重写、只读、离线第一句就框定任务范围Write an editorialized replacement for only the newest release section inCHANGELOG.md.紧接着划定事实来源与安全边界允许读取CHANGELOG.md和本地 Git 历史禁止编辑任何文件、禁止使用网络。也就是说模型只能产出“候选文本”落盘动作完全交给下游脚本见 scripts/update-latest-changelog-section.py。这与 workflow 中:read-only权限配置是双重保险即使提示词被绕过文件系统层面也无法写入。风格对齐以前几版为准必要时下钻到 diff提示词要求模型对比多个历史版本使新版小节的“section names、ordering、tone、Markdown style”与既有风格一致当自动生成的标题不足以准确分类或描述某条变更时应**检查本地对应的变更内容diff**再下笔。这解释了为什么 workflow 使用fetch-depth: 0完整 checkout——模型需要完整的提交历史来做“inspect the included local changes”。引用格式GitHub 规范形式对所有 GitHub 面向的产出issue/PR 引用必须写成owner/repository#number规范形式如astral-sh/uv#123、astral-sh/uv-dev#123以保留跨仓库的 closing keyword 能力并让 GitHub 渲染成链接禁止裸数字、仓库名缩写、Markdown 链接语法或反引号包裹同时保持CHANGELOG.md中既有的引用格式。编辑规则Apply these rules这是提示词的核心共八条逐条对应 changelog 的常见腐化方式保留版本号与日期小节标题与Released on ...行不可变。保留每条保留条目的 PR 号与精确 URL绝不修改 URL自动生成的 changelog 条目携带[#21408](https://github.com/astral-sh/uv/pull/21408)形式的链接重写只改文案不动引用。每个段落与列表项保持单行不做硬换行提示词明确指出“wrapping can break rendering on GitHub”——长行在 GitHub 的 Markdown 渲染中会正常折行显示而源码中的硬换行会让 diff、锚点和后续工具处理变复杂。删除纯内部条目CI/测试 runner 变更、仓库重组、agent 或开发者基础设施等“对用户无影响”的条目应删除效果不确定时保留——这是一个典型的保守策略宁可冗余不可漏报用户可见变更。Enhancements与Bug fixes的归属是仓库元数据绝不互挪也禁止把条目从Bug fixes挪到Performance。这防止模型“自作主张”地重新归类已被维护者确认的条目。功能区覆盖规则feature-area override只在无歧义时生效对 preview 功能的任何修改即使是修 bug保持在Preview featuresPython 运行时或 Python 发行版相关变更归Python只有当本地变更的主要意图是性能时才允许把条目从Enhancements/Other changes移入PerformanceOther changes的条目只有在本地产变更能无歧义地归入某个既有分组时才移动没有合适分组但属于用户/生态相关维护工作如 MSRV、工具链更新、面向下游集成的公共 API 兼容性的条目保留在Other changes。生成的文案只是“原材料”而非“优选基线”保留下来的条目要重写得更清晰、更精确、更面向用户——展开内部缩写、补充本地变更所支持的上下文但必须保持原意不得发明或夸大声明也避免纯同义词替换式的“为改而改”。排序与清理每个分组内把用户可见影响最大的条目放最前面并删除变空的分组。输出契约一段、一个##行、无围栏提示词结尾给出严格的输出格式约束Return only the complete replacement release section, beginning with its##heading. Do not include the next release heading, any older changelog content, a code fence, or commentary. Your response must contain exactly one line that begins with##;###subsection headings are expected.即响应体本身必须是从##开始、恰好包含一行#####子标题可以有的完整小节不带代码围栏、不带解释。这条契约是为了让下游脚本可以零解析成本地直接消费输出——模型输出即是“最终文件片段”。落盘脚本确定性替换最新小节scripts/update-latest-changelog-section.py 是一个极小的脚本文件头带# /// script内联元数据可用uv run直接执行其核心逻辑是preamble, _, historical_releases changelog.split(\n## , maxsplit2) args.changelog.write_text( f{preamble}\n{candidate}\n\n## {historical_releases}, encodingutf-8, )它按提示词定义的边界第一个##标题把 changelog 切成preamble与historical_releases两段用模型候选文本整体替换中间的最新小节再原样拼回——maxsplit2确保即使历史内容中还有##标题也不会被误切。candidate先经rstrip(\n)处理保证拼接后恰好一个空行分隔。由于提示词要求响应体必须以##开头且不含旧内容这里没有任何正则清洗或防御性解析整个替换是纯字符串拼接LLM 的不确定性被隔离在“生成候选”这一步落盘路径则是确定性的。从这套机制可以复用的工程经验从源码结构看uv 在“让 LLM 参与发布流程”上做了三层约束值得借鉴提示词即契约editorialize-changelog.md 不是一份“建议”而是定义了任务范围只动最新小节、事实边界本地文件 git 历史禁网、内容规则八条编辑规则和输出契约恰好一行##四份合同prompt 文件与 workflow 解耦CI 只是cat拼接版本上下文见 release-prepare.yml 第 69–74 行prompt 演进不需要改 workflow。权限最小化Codex 以:read-only权限 profile 运行agents/codex/config.toml 中default_permissions :read-only是仓库内 Codex 会话的同类约定模型物理上无法写文件写盘只发生在 workflow 的“Apply changelog rewrite”一步。可验证、可回滚落盘后先git diff --check空白错误检查无变化则跳过提交“Codex left the generated changelog unchanged.”有变化才单独提交Rewrite changelog——changelog 重写是独立提交方便审查与 revert。对维护类似 changelog 的项目这套模式的最小迁移路径是把“最新版小节边界”“分组归属不可动”“URL 不可动”“输出必须是单个完整小节”这几条硬约束写成提示词再用一个十余行的 Python 脚本做split(\n## , maxsplit2)式替换落盘即可获得“LLM 负责风格与措辞、脚本负责正确性”的自动化发布说明流水线。参考文件提示词主体editorialize-changelog.md发布准备流水线release-prepare.yml小节替换脚本update-latest-changelog-section.py归档辅助脚本reverse-changelog.py版本提升脚本release.sh发布流程文档CONTRIBUTING.mdReleases 一节变更历史示例CHANGELOG.md、归档文件 changelogs/0.1.x.md【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考