拓冰网站定制 
文档【免费下载链接】keep-a-changelogIf you build software, keep a changelog.项目地址https://gitcode.com/gh_mirrors/ke/keep-a-changelog点击查看免费下载本篇技术指南以 keep-a-changelog 仓库自身的 CHANGELOG.md 为骨架完整梳理该项目从 2014 年首个版本到 2026 年 2.0.0 重大改版的十二年演进史并深入解读围绕这份文件构建的两套自动化工具——版本固定pinning与发布同步release sync的源码级实现。读者读完后既能理解 Keep a Changelog 规范在格式、指引与翻译生态上的历次关键决策也能掌握「以 CHANGELOG.md 为唯一事实来源」的工程化落地方法。一、为什么这份 CHANGELOG 本身就是最好的教学案例Keep a Changelog 的核心理念是「软件作者应维护一份人类可读的变更日志」而本项目把这一理念贯彻到了极致项目自己的 CHANGELOG.md 就是官方规范的最佳示例。它从 0.0.12014-05-31一路记录到 2.0.02026-06-07每一处条目、每一个标记都是规范自身演进的活标本。文件头部声明的两条元信息是理解全文的钥匙The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.格式基准遵循 Keep a Changelog 2.0.0 规范版本策略遵循 Semantic Versioning语义化版本以下简称 SemVer。这份文件同时承担三个角色项目发布记录按时间倒序记录每一次正式发布规范活示例展示六种变更类型Added/Changed/Fixed/Removed/Security等、YYYY-MM-DD日期格式、Unreleased与[YANKED]标记的用法自动化数据源仓库内的 tools/changelog_pin.rb 与 tools/changelog_release.rb 都直接解析这份文件来驱动网站内容与 GitHub Releases使其成为名副其实的「single source of truth」。从文件结构看CHANGELOG.md它严格遵循了规范要求的骨架Unreleased段在最上方、已发布版本按倒序排列、每个版本条目内部再按变更类型分组文件末尾以引用式链接reference links统一维护每个版本的compare对比链接。二、2.0.0规范十年来的首次重大修订2026-06-072.0.0 是整个文件的核心章节也是理解本次演进意图的枢纽。版本说明开宗明义2.0.0 is the first major revision of Keep a Changelog. It breaks the guidance, not the format.这句话概括了 2.0.0 的全部哲学打破的是指引guidance不是格式format。六个变更类型、YYYY-MM-DD日期、Unreleased与[YANKED]标记全部保持不变因此既有项目的 changelog 依然有效被破坏的是「表面层」——页面结构、旧章节锚点、推荐指引以及尚未跟进的翻译。2.1 Added回答社区十年反复追问的问题2.0.0 新增指引覆盖了六大主题可以逐一对照 docs/2.0.0-PLAN.md 中的规划决策来理解其来龙去脉新增主题核心内容对应的规划决策格式Format# Changelog头部前言的写法如何标记破坏性变更及升级步骤放哪里Changed/Fixed/Security如何取舍Security 条目以 CVE 开头为什么六种变更类型不扩张Tier 1 #1破坏性变更用**Breaking:**前缀 SemVer 映射、Tier 3 #9类型集保持六个版本Versioning超越 SemVer 的其他方案为每个版本链接compare差异引用链接Tier 1 #3CalVer、日期制、持续交付方案Changelog vs 发布说明如何从 changelog 派生 release notes 而不重复劳动宿主平台自动生成的 notes 是供应商锁定Tier 1 #2changelog 是「给人读仓库的人」的文档release notes 是派生视图自动化为AGENTS.md提供 brief 让 LLM 起草 changelogConventional CommitsCI/CD链接 issue/PR为贡献者署名规划文档「human LLM layer」章节规模超大 changelog 与 monorepo 的处理Tier 2 #6、#8边界可选的每版本摘要明确声明 Keep a Changelog 刻意不做的事Tier 2 #5规划文档「Explicit non-goals」其中「机器起草、人类策展」machines draft, humans curate是 2.0.0 在 LLM 时代的核心论点当 AI 能在几秒内根据 diff 生成一份流畅的 changelog 时风险不是没有 changelog而是一份从未被人类读过的自动生成文本。这一主张在 docs/2.0.0-PLAN.md 中表述为「Making changes and communicating about changes are two fundamentally different things」——变更与沟通变更是两件根本不同的事。2.2 Changed / Removed三处破坏性变更与一处重构2.0.0 明确标注了破坏性变更**Breaking:**口号退役弃用「Dont let your friends dump git logs into changelogs」改用「Clearly document the evolution of your projects」。注意旧版本页面保留原口号——这正是下文「版本固定」机制存在的理由之一页面重构从扁平 FAQ 结构改为一体化指引integrated guidance语气从第一人称改为更平实的第三人称导致部分旧章节锚点失效FAQ 脚手架移除旧 FAQ 骨架与大部分第一人称框架被删除其章节锚点不再解析播客注记移入 References 章节。非破坏性改动包括将「GitHub Releases」问答重构为「Is a changelog the same as release notes?」并把讨论范围从 GitHub 扩展到任意托管平台页面标题与描述改为从 frontmatter 读取并修复 OpenGraph 元数据使分享链接在不同语言下正确渲染。整个站点还完成了 WCAG 2.1 AA 级别的无障碍重构并支持明暗双主题。2.3 与规划文档的印证docs/2.0.0-PLAN.md 中的关键决策在 CHANGELOG 中都有落点破坏性变更决议Tier 1 #1不新增Breaking分区避免与Removed/Changed重复、碎片化六类型而是在相关条目前加**Breaking:**前缀同时明确「major 版本号跃升本身就意味着破坏性变更」changelog 的职责是让升级阵痛一目了然六类型不扩张决议Tier 3 #9Improved、Optimized、Refactored、Performance等是「原因/细节」而非「变更种类」应写进条目正文而非成为新类型Dependencies不是面向人类的变更种类Known Issues是发现而非变更Changed/Fixed/Security边界Tier 3 #10Fixed是错误行为被纠正Changed是原本按预期工作的行为以不同方式工作Security是解决漏洞的修复或变更——因受众与紧迫性不同而单独列出。三、Unreleased 段与「版本固定」机制让每个规范页面展示自己时代的示例CHANGELOG 当前Unreleased段只有一条记录Older spec pages no longer display an example changelog written to newer conventions than the page describes: each pages example is now pinned to its own versions last release, derived at build time from this file.这条 Fixed 条目描述了一个精妙的设计问题每个规范页面如/en/1.1.0/上展示的「示例 changelog」必须与其所讲解的规范版本一致。假如 2.0.0 已经发布而 1.1.0 页面仍展示按 2.0.0 新规范书写的示例读者就会被误导对应 issue #720 的报告。解决方案不是为每个版本维护快照文件或多分支跟踪——生产部署基于单一浅克隆shallow checkout构建时根本没有其他分支和 tag 可用——而是在渲染时从唯一的 CHANGELOG.md 实时派生「版本固定视图」。实现位于 tools/changelog_pin.rb其核心逻辑判定是否需要固定pinned?找出 changelog 中记录的最新版本若其 major.minor track 高于页面版本则旧版本页面必须固定changelog_pin.rb找到轨道上的最后发布track_releasepatch 版本只发布翻译与站点修复、不改变规范因此 2.0.0 页面固定到最后一个 2.0.x 而非 2.0.0 本身changelog_pin.rb执行固定pinchangelog_pin.rb删除比页面轨道更新的版本条目及其版本链接定义Unreleased段保留标题但清空内容标题本身是规范格式的一部分其内容则属于比该轨道更新的工作将[unreleased]对比链接重写为从该轨道最后发布版本 diff 到 HEAD将前言中引用的规范 URL 重写为页面版本。test/changelog_pin_test.rb 用「假设未来 3.0.0 已发布」的 fixture 验证了全部规则包括数字版本比较2.0.10 2.0.2而非字典序、最新轨道页面展示活文件、无 dated 条目的 changelog 永不固定、被丢弃条目的链接定义同步删除而普通链接如[someone]:保留。四、发布同步工具CHANGELOG 即发布真相CHANGELOG 也是 GitHub Releases 的唯一来源。文档第 1.1.1 条记录了「Centralize all links into/data/links.json」这样的基础设施演进而自动化层面由 tools/changelog_release.rb 承担每个已发布的版本都从 CHANGELOG.md 派生changelog 是真相发布是派生物。4.1 命令行用法# 为每个尚无 release 的 dated 版本创建 release幂等已存在则跳过 ruby tools/changelog_release.rb create # 创建缺失 release 后再核对所有已存在 release 的正文与 changelog 是否一致不一致则更新 ruby tools/changelog_release.rb sync # 只打印计划、不改动任何东西并通过 GITHUB_OUTPUT 输出 changestrue/false 供工作流门禁 ruby tools/changelog_release.rb create --dry-run ruby tools/changelog_release.rb sync --dry-run4.2 解析与同步的源码细节条目解析ChangelogRelease.parsechangelog_release.rb用正则^\#\#\s*\[(?version\d\.\d\.\d)\]\s*-\s*(?date\d{4}-\d{2}-\d{2})匹配 dated 版本标题跳过Unreleased容忍尾部[YANKED]标记每个条目解析出version、tag自动加v前缀、date、yanked与notes正文截取到下一个版本标题或文末链接定义块为止归一化比较normalize统一换行符、去除每行尾部空白、去掉首尾空行使纯外观差异不视为「漂移」但保留内部空行——这正是判断 release 正文是否与 changelog 漂移的依据changelog_release.rb漂移检测unified_diff基于最长公共子序列LCS做行级 diff长段未变行折叠为 N unchanged line(s) 标记保持 dry-run 计划可读changelog_release.rb创建流程create_missing按时间从旧到新补齐缺失 releasetag 缺失时创建带注释的 annotated tag且用GIT_AUTHOR_DATE/GIT_COMMITTER_DATE环境变量把 tag 日期戳为 changelog 条目日期使 tag 携带正确日期changelog_release.rb同步流程sync_all对每个已存在 release若归一化后的正文与 changelog 不一致则更新——这正是「发布后给某版本补了翻译要推送到已发布 release」的场景可测试性设计所有 GitHub/git 访问收敛在注入的GitHubCli适配器中test/changelog_release_test.rb 用FakeGitHub在内存中模拟 release/tag 状态无需联网即可验证全部编排逻辑包括[YANKED]标题0.0.5 [YANKED]、幂等跳过、纯外观差异不触发更新等。五、翻译生态1.x 时代的主旋律1.1.2 与 1.1.1 的绝大多数条目是翻译工作这反映了该项目运营模式的一个关键特征站点内容按版本多语言并行维护每个语言目录如source/zh-CN/1.1.0/下保存各版本的index.html.haml。从 CONTRIBUTING.md 可以确认翻译流程是人工工作项目不使用 LLM 替代译者自动化检查ruby translation_coverage.rb、bin/rake translations:lint、bin/rake translations:qa只负责找缺口与不一致不负责撰写或批准翻译1.1.1 引入「默认展示每种语言可获得的最新版本」「显示可用翻译计数当时 26 种」以及「将所有链接集中到/data/links.json」的基础设施改进1.1.0 起翻译目录按 ISO 639-1 语言码组织仓库中可见ar、da、fa、hr、id、ja、ka、ko、nb、ro、sk、sr、uk、zh-CN、zh-TW等 20 余种语言目录与 CHANGELOG 中记录的贡献者一一对应。六、1.0.0 与更早版本规范奠基史1.0.02017-06-20是规范成型的里程碑新增「Why keep a changelog?」「Who needs a changelog?」「How do I make a changelog?」「Frequently Asked Questions」四大章节及「Guiding Principles」子节并引入了版本导航、旧版本页链接到最新发布等站点机制——这些机制正是如今 2.0.0 重构与版本固定机制的前身。同时确立了「changelog」而非「change log」的用词并将版本号与英文原版 0.3.0 对齐方便翻译作者跟进。更早的版本则记录了格式规则的一步步成型版本日期关键决策0.0.12014-05-31创建本 CHANGELOG 文件作为标准化示例README 收录常见问题、基本指引与日期格式加入反面教材「What makes unicorns cry?」0.0.22014-07-10说明推荐的倒序发布排列0.0.32014-08-09增加「Why should I care?」章节0.0.42014-08-09区分文件CHANGELOG与功能change log并移除空章节——空章节占用空间、制造噪音缺失的章节意味着「没有值得记录的变更」0.0.52014-08-09发布标题上增加版本 tag 的 Markdown 链接新增Unreleased段收集未发布变更0.0.62014-12-12README 增加「yanked」发布章节0.0.72015-02-16明确日期格式为 ISO 8601改为脚注式链接0.0.82015-02-17统一 README 示例年份修正失效的 unreleased diff 链接0.1.02015-10-06回答「Should you ever rewrite a change log?」开始正式遵循 SemVer0.2.02015-10-06移除「open source」排他性表述承认对开源与闭源项目同样有益0.3.02015-12-03新增俄语、巴西葡语、西语翻译值得注意的是 0.0.4 的「移除空章节」决策这解释了为何本 CHANGELOG 的旧版本条目只出现实际发生变更的类型分组——缺失即代表「无值得记录之变更」这是规范自身的忠实实践。而 0.0.5 引入的Unreleased段则在 2.0.0 时代被 tools/changelog_pin.rb 保留了标题、清空了内容——格式未变机制进化。七、可验证的自动化闭环与工程启示将 CHANGELOG、源码与测试三者对照可以画出一条完整的工程闭环维护在 CHANGELOG.md 的Unreleased段按六类型撰写新条目这是唯一需要人工维护的事实来源网站示例各规范页面的「示例 changelog」由 tools/changelog_pin.rb 在构建时从该文件派生保证与页面版本一致见 test/changelog_pin_test.rb 中对真实 CHANGELOG 的不变式断言发布ruby tools/changelog_release.rb create|sync将 dated 版本同步为 GitHub Releasestag 日期取自条目日期正文漂移可被 dry-run 计划检出见 test/changelog_release_test.rb翻译跟进通过source/下各语言目录与 TRANSLATION_COVERAGE.md 配套的覆盖率工具管理多语言债务。对任何维护者而言这个仓库最重要的工程启示是让 CHANGELOG.md 成为单一事实来源用纯函数式的派生逻辑无框架、可单测把「示例展示」和「发布同步」变成构建时/CI 时自动完成的事情——既消灭了「发布检查清单」这类容易遗忘的步骤又让旧条目随后的文字修订能自动传导到所有固定视图。这正符合 CHANGELOG 2.0.0 对自动化的一贯立场机器起草、人类策展规范保持为约定而非运行时。赞分享文档【免费下载链接】keep-a-changelogIf you build software, keep a changelog.项目地址https://gitcode.com/gh_mirrors/ke/keep-a-changelog点击查看免费下载相关推荐Keep a Changelog从 CHANGELOG.md 规范到 keepachangelog.com 站点实现Keep a Changelog从 CHANGELOG.md 规范到 keepachangelog.com 站点实现 Keep a Changelog 是基文档Keep a Changelog 2.0 深度指南用 CHANGELOG.md 记录项目演进的完整规范与工程实践Keep a Changelog 2.0 深度指南用 CHANGELOG.md 记录项目演进的完整规范与工程实践 导读 本文以 keep a changel文档web3.js 仓库 CHANGELOG 规范与实践基于 Keep a Changelog 与 SemVer 的自动化维护指南web3.js 仓库 CHANGELOG 规范与实践基于 Keep a Changelog 与 SemVer 的自动化维护指南 本篇技术指南以 web3.js区块链Web3上一篇CompressO终极指南如何免费压缩视频图片释放90%存储空间下一篇CompressO免费开源的终极媒体压缩工具一键将视频图片缩小90%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Keep a Changelog 官方仓库 CHANGELOG.md 全解析：从 0.0.1 到 2.0.0 的规范演进与自动化工程实践
文档【免费下载链接】keep-a-changelogIf you build software, keep a changelog.项目地址https://gitcode.com/gh_mirrors/ke/keep-a-changelog点击查看免费下载本篇技术指南以 keep-a-changelog 仓库自身的 CHANGELOG.md 为骨架完整梳理该项目从 2014 年首个版本到 2026 年 2.0.0 重大改版的十二年演进史并深入解读围绕这份文件构建的两套自动化工具——版本固定pinning与发布同步release sync的源码级实现。读者读完后既能理解 Keep a Changelog 规范在格式、指引与翻译生态上的历次关键决策也能掌握「以 CHANGELOG.md 为唯一事实来源」的工程化落地方法。一、为什么这份 CHANGELOG 本身就是最好的教学案例Keep a Changelog 的核心理念是「软件作者应维护一份人类可读的变更日志」而本项目把这一理念贯彻到了极致项目自己的 CHANGELOG.md 就是官方规范的最佳示例。它从 0.0.12014-05-31一路记录到 2.0.02026-06-07每一处条目、每一个标记都是规范自身演进的活标本。文件头部声明的两条元信息是理解全文的钥匙The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.格式基准遵循 Keep a Changelog 2.0.0 规范版本策略遵循 Semantic Versioning语义化版本以下简称 SemVer。这份文件同时承担三个角色项目发布记录按时间倒序记录每一次正式发布规范活示例展示六种变更类型Added/Changed/Fixed/Removed/Security等、YYYY-MM-DD日期格式、Unreleased与[YANKED]标记的用法自动化数据源仓库内的 tools/changelog_pin.rb 与 tools/changelog_release.rb 都直接解析这份文件来驱动网站内容与 GitHub Releases使其成为名副其实的「single source of truth」。从文件结构看CHANGELOG.md它严格遵循了规范要求的骨架Unreleased段在最上方、已发布版本按倒序排列、每个版本条目内部再按变更类型分组文件末尾以引用式链接reference links统一维护每个版本的compare对比链接。二、2.0.0规范十年来的首次重大修订2026-06-072.0.0 是整个文件的核心章节也是理解本次演进意图的枢纽。版本说明开宗明义2.0.0 is the first major revision of Keep a Changelog. It breaks the guidance, not the format.这句话概括了 2.0.0 的全部哲学打破的是指引guidance不是格式format。六个变更类型、YYYY-MM-DD日期、Unreleased与[YANKED]标记全部保持不变因此既有项目的 changelog 依然有效被破坏的是「表面层」——页面结构、旧章节锚点、推荐指引以及尚未跟进的翻译。2.1 Added回答社区十年反复追问的问题2.0.0 新增指引覆盖了六大主题可以逐一对照 docs/2.0.0-PLAN.md 中的规划决策来理解其来龙去脉新增主题核心内容对应的规划决策格式Format# Changelog头部前言的写法如何标记破坏性变更及升级步骤放哪里Changed/Fixed/Security如何取舍Security 条目以 CVE 开头为什么六种变更类型不扩张Tier 1 #1破坏性变更用**Breaking:**前缀 SemVer 映射、Tier 3 #9类型集保持六个版本Versioning超越 SemVer 的其他方案为每个版本链接compare差异引用链接Tier 1 #3CalVer、日期制、持续交付方案Changelog vs 发布说明如何从 changelog 派生 release notes 而不重复劳动宿主平台自动生成的 notes 是供应商锁定Tier 1 #2changelog 是「给人读仓库的人」的文档release notes 是派生视图自动化为AGENTS.md提供 brief 让 LLM 起草 changelogConventional CommitsCI/CD链接 issue/PR为贡献者署名规划文档「human LLM layer」章节规模超大 changelog 与 monorepo 的处理Tier 2 #6、#8边界可选的每版本摘要明确声明 Keep a Changelog 刻意不做的事Tier 2 #5规划文档「Explicit non-goals」其中「机器起草、人类策展」machines draft, humans curate是 2.0.0 在 LLM 时代的核心论点当 AI 能在几秒内根据 diff 生成一份流畅的 changelog 时风险不是没有 changelog而是一份从未被人类读过的自动生成文本。这一主张在 docs/2.0.0-PLAN.md 中表述为「Making changes and communicating about changes are two fundamentally different things」——变更与沟通变更是两件根本不同的事。2.2 Changed / Removed三处破坏性变更与一处重构2.0.0 明确标注了破坏性变更**Breaking:**口号退役弃用「Dont let your friends dump git logs into changelogs」改用「Clearly document the evolution of your projects」。注意旧版本页面保留原口号——这正是下文「版本固定」机制存在的理由之一页面重构从扁平 FAQ 结构改为一体化指引integrated guidance语气从第一人称改为更平实的第三人称导致部分旧章节锚点失效FAQ 脚手架移除旧 FAQ 骨架与大部分第一人称框架被删除其章节锚点不再解析播客注记移入 References 章节。非破坏性改动包括将「GitHub Releases」问答重构为「Is a changelog the same as release notes?」并把讨论范围从 GitHub 扩展到任意托管平台页面标题与描述改为从 frontmatter 读取并修复 OpenGraph 元数据使分享链接在不同语言下正确渲染。整个站点还完成了 WCAG 2.1 AA 级别的无障碍重构并支持明暗双主题。2.3 与规划文档的印证docs/2.0.0-PLAN.md 中的关键决策在 CHANGELOG 中都有落点破坏性变更决议Tier 1 #1不新增Breaking分区避免与Removed/Changed重复、碎片化六类型而是在相关条目前加**Breaking:**前缀同时明确「major 版本号跃升本身就意味着破坏性变更」changelog 的职责是让升级阵痛一目了然六类型不扩张决议Tier 3 #9Improved、Optimized、Refactored、Performance等是「原因/细节」而非「变更种类」应写进条目正文而非成为新类型Dependencies不是面向人类的变更种类Known Issues是发现而非变更Changed/Fixed/Security边界Tier 3 #10Fixed是错误行为被纠正Changed是原本按预期工作的行为以不同方式工作Security是解决漏洞的修复或变更——因受众与紧迫性不同而单独列出。三、Unreleased 段与「版本固定」机制让每个规范页面展示自己时代的示例CHANGELOG 当前Unreleased段只有一条记录Older spec pages no longer display an example changelog written to newer conventions than the page describes: each pages example is now pinned to its own versions last release, derived at build time from this file.这条 Fixed 条目描述了一个精妙的设计问题每个规范页面如/en/1.1.0/上展示的「示例 changelog」必须与其所讲解的规范版本一致。假如 2.0.0 已经发布而 1.1.0 页面仍展示按 2.0.0 新规范书写的示例读者就会被误导对应 issue #720 的报告。解决方案不是为每个版本维护快照文件或多分支跟踪——生产部署基于单一浅克隆shallow checkout构建时根本没有其他分支和 tag 可用——而是在渲染时从唯一的 CHANGELOG.md 实时派生「版本固定视图」。实现位于 tools/changelog_pin.rb其核心逻辑判定是否需要固定pinned?找出 changelog 中记录的最新版本若其 major.minor track 高于页面版本则旧版本页面必须固定changelog_pin.rb找到轨道上的最后发布track_releasepatch 版本只发布翻译与站点修复、不改变规范因此 2.0.0 页面固定到最后一个 2.0.x 而非 2.0.0 本身changelog_pin.rb执行固定pinchangelog_pin.rb删除比页面轨道更新的版本条目及其版本链接定义Unreleased段保留标题但清空内容标题本身是规范格式的一部分其内容则属于比该轨道更新的工作将[unreleased]对比链接重写为从该轨道最后发布版本 diff 到 HEAD将前言中引用的规范 URL 重写为页面版本。test/changelog_pin_test.rb 用「假设未来 3.0.0 已发布」的 fixture 验证了全部规则包括数字版本比较2.0.10 2.0.2而非字典序、最新轨道页面展示活文件、无 dated 条目的 changelog 永不固定、被丢弃条目的链接定义同步删除而普通链接如[someone]:保留。四、发布同步工具CHANGELOG 即发布真相CHANGELOG 也是 GitHub Releases 的唯一来源。文档第 1.1.1 条记录了「Centralize all links into/data/links.json」这样的基础设施演进而自动化层面由 tools/changelog_release.rb 承担每个已发布的版本都从 CHANGELOG.md 派生changelog 是真相发布是派生物。4.1 命令行用法# 为每个尚无 release 的 dated 版本创建 release幂等已存在则跳过 ruby tools/changelog_release.rb create # 创建缺失 release 后再核对所有已存在 release 的正文与 changelog 是否一致不一致则更新 ruby tools/changelog_release.rb sync # 只打印计划、不改动任何东西并通过 GITHUB_OUTPUT 输出 changestrue/false 供工作流门禁 ruby tools/changelog_release.rb create --dry-run ruby tools/changelog_release.rb sync --dry-run4.2 解析与同步的源码细节条目解析ChangelogRelease.parsechangelog_release.rb用正则^\#\#\s*\[(?version\d\.\d\.\d)\]\s*-\s*(?date\d{4}-\d{2}-\d{2})匹配 dated 版本标题跳过Unreleased容忍尾部[YANKED]标记每个条目解析出version、tag自动加v前缀、date、yanked与notes正文截取到下一个版本标题或文末链接定义块为止归一化比较normalize统一换行符、去除每行尾部空白、去掉首尾空行使纯外观差异不视为「漂移」但保留内部空行——这正是判断 release 正文是否与 changelog 漂移的依据changelog_release.rb漂移检测unified_diff基于最长公共子序列LCS做行级 diff长段未变行折叠为 N unchanged line(s) 标记保持 dry-run 计划可读changelog_release.rb创建流程create_missing按时间从旧到新补齐缺失 releasetag 缺失时创建带注释的 annotated tag且用GIT_AUTHOR_DATE/GIT_COMMITTER_DATE环境变量把 tag 日期戳为 changelog 条目日期使 tag 携带正确日期changelog_release.rb同步流程sync_all对每个已存在 release若归一化后的正文与 changelog 不一致则更新——这正是「发布后给某版本补了翻译要推送到已发布 release」的场景可测试性设计所有 GitHub/git 访问收敛在注入的GitHubCli适配器中test/changelog_release_test.rb 用FakeGitHub在内存中模拟 release/tag 状态无需联网即可验证全部编排逻辑包括[YANKED]标题0.0.5 [YANKED]、幂等跳过、纯外观差异不触发更新等。五、翻译生态1.x 时代的主旋律1.1.2 与 1.1.1 的绝大多数条目是翻译工作这反映了该项目运营模式的一个关键特征站点内容按版本多语言并行维护每个语言目录如source/zh-CN/1.1.0/下保存各版本的index.html.haml。从 CONTRIBUTING.md 可以确认翻译流程是人工工作项目不使用 LLM 替代译者自动化检查ruby translation_coverage.rb、bin/rake translations:lint、bin/rake translations:qa只负责找缺口与不一致不负责撰写或批准翻译1.1.1 引入「默认展示每种语言可获得的最新版本」「显示可用翻译计数当时 26 种」以及「将所有链接集中到/data/links.json」的基础设施改进1.1.0 起翻译目录按 ISO 639-1 语言码组织仓库中可见ar、da、fa、hr、id、ja、ka、ko、nb、ro、sk、sr、uk、zh-CN、zh-TW等 20 余种语言目录与 CHANGELOG 中记录的贡献者一一对应。六、1.0.0 与更早版本规范奠基史1.0.02017-06-20是规范成型的里程碑新增「Why keep a changelog?」「Who needs a changelog?」「How do I make a changelog?」「Frequently Asked Questions」四大章节及「Guiding Principles」子节并引入了版本导航、旧版本页链接到最新发布等站点机制——这些机制正是如今 2.0.0 重构与版本固定机制的前身。同时确立了「changelog」而非「change log」的用词并将版本号与英文原版 0.3.0 对齐方便翻译作者跟进。更早的版本则记录了格式规则的一步步成型版本日期关键决策0.0.12014-05-31创建本 CHANGELOG 文件作为标准化示例README 收录常见问题、基本指引与日期格式加入反面教材「What makes unicorns cry?」0.0.22014-07-10说明推荐的倒序发布排列0.0.32014-08-09增加「Why should I care?」章节0.0.42014-08-09区分文件CHANGELOG与功能change log并移除空章节——空章节占用空间、制造噪音缺失的章节意味着「没有值得记录的变更」0.0.52014-08-09发布标题上增加版本 tag 的 Markdown 链接新增Unreleased段收集未发布变更0.0.62014-12-12README 增加「yanked」发布章节0.0.72015-02-16明确日期格式为 ISO 8601改为脚注式链接0.0.82015-02-17统一 README 示例年份修正失效的 unreleased diff 链接0.1.02015-10-06回答「Should you ever rewrite a change log?」开始正式遵循 SemVer0.2.02015-10-06移除「open source」排他性表述承认对开源与闭源项目同样有益0.3.02015-12-03新增俄语、巴西葡语、西语翻译值得注意的是 0.0.4 的「移除空章节」决策这解释了为何本 CHANGELOG 的旧版本条目只出现实际发生变更的类型分组——缺失即代表「无值得记录之变更」这是规范自身的忠实实践。而 0.0.5 引入的Unreleased段则在 2.0.0 时代被 tools/changelog_pin.rb 保留了标题、清空了内容——格式未变机制进化。七、可验证的自动化闭环与工程启示将 CHANGELOG、源码与测试三者对照可以画出一条完整的工程闭环维护在 CHANGELOG.md 的Unreleased段按六类型撰写新条目这是唯一需要人工维护的事实来源网站示例各规范页面的「示例 changelog」由 tools/changelog_pin.rb 在构建时从该文件派生保证与页面版本一致见 test/changelog_pin_test.rb 中对真实 CHANGELOG 的不变式断言发布ruby tools/changelog_release.rb create|sync将 dated 版本同步为 GitHub Releasestag 日期取自条目日期正文漂移可被 dry-run 计划检出见 test/changelog_release_test.rb翻译跟进通过source/下各语言目录与 TRANSLATION_COVERAGE.md 配套的覆盖率工具管理多语言债务。对任何维护者而言这个仓库最重要的工程启示是让 CHANGELOG.md 成为单一事实来源用纯函数式的派生逻辑无框架、可单测把「示例展示」和「发布同步」变成构建时/CI 时自动完成的事情——既消灭了「发布检查清单」这类容易遗忘的步骤又让旧条目随后的文字修订能自动传导到所有固定视图。这正符合 CHANGELOG 2.0.0 对自动化的一贯立场机器起草、人类策展规范保持为约定而非运行时。赞分享文档【免费下载链接】keep-a-changelogIf you build software, keep a changelog.项目地址https://gitcode.com/gh_mirrors/ke/keep-a-changelog点击查看免费下载相关推荐Keep a Changelog从 CHANGELOG.md 规范到 keepachangelog.com 站点实现Keep a Changelog从 CHANGELOG.md 规范到 keepachangelog.com 站点实现 Keep a Changelog 是基文档Keep a Changelog 2.0 深度指南用 CHANGELOG.md 记录项目演进的完整规范与工程实践Keep a Changelog 2.0 深度指南用 CHANGELOG.md 记录项目演进的完整规范与工程实践 导读 本文以 keep a changel文档web3.js 仓库 CHANGELOG 规范与实践基于 Keep a Changelog 与 SemVer 的自动化维护指南web3.js 仓库 CHANGELOG 规范与实践基于 Keep a Changelog 与 SemVer 的自动化维护指南 本篇技术指南以 web3.js区块链Web3上一篇CompressO终极指南如何免费压缩视频图片释放90%存储空间下一篇CompressO免费开源的终极媒体压缩工具一键将视频图片缩小90%创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考