Leiningen `lein new template` 生成的 CHANGELOG.md 模板：Keep a Changelog 规范与 Mustache 变量注入机制

构建工具CLI【免费下载链接】leiningenMoved to Codeberg; this is a temporary convenience mirror项目地址https://gitcode.com/gh_mirrors/le/leiningen点击查看免费下载lein new template生成的 CHANGELOG.md 模板是 Leiningen 为模板类项目预置的变更日志骨架文件它遵循 keepachangelog.com 的社区约定并借助 Leiningen 模板渲染引擎将{{date}}、{{name}}等 Mustache 变量在生成时动态替换为实际值。本文以 resources/leiningen/new/template/CHANGELOG.md 为蓝本结合 模板生成源码 与 渲染引擎实现完整讲解该模板的章节结构、版本占位符、发布日期注入方式以及如何在生成后的模板项目中维护真实的变更日志。一、模板在项目中的定位模板项目的“骨架文档”之一在 Leiningen 中lein new template name用于生成一个“模板项目”——即一个专门用来生成其他项目的元模板meta-template。执行该命令时src/leiningen/new/template.clj 中的template函数会调用t/-files一次性生成以下文件生成文件说明README.md模板使用说明project.clj模板项目自身的defproject配置.gitignore/.hgignoreGit / Mercurial 忽略文件src/leiningen/new/{{sanitized}}.clj模板的核心实现代码由temp.clj渲染resources/leiningen/new/{{sanitized}}/foo.clj模板资源样例LICENSE许可证文件CHANGELOG.md变更日志本文主角对应测试 test/leiningen/test/new.clj 中明确断言执行new/new nil template test-new-template后生成的目录内必须包含CHANGELOG.md与其他模板类型default、app、plugin的生成结果保持一致——可见变更日志文件是每个新项目骨架的标配。二、CHANGELOG.md 模板逐段解析该模板全文如下渲染前# Change Log All notable changes to this project will be documented in this file. This change log follows the conventions of keepachangelog.com. ## [Unreleased] ### Changed - Add a new arity to make-widget-async to provide a different widget shape. ## [0.1.1] - {{date}} ### Changed - Documentation on how to make the widgets. ### Removed - make-widget-sync - were all async, all the time. ### Fixed - Fixed widget maker to keep working when daylight savings switches over. ## 0.1.0 - {{date}} ### Added - Files from the new template. - Widget maker public API - make-widget-sync. [Unreleased]: https://source-host.site/your-name/{{name}}/compare/0.1.1...HEAD [0.1.1]: https://source-host.site/your-name/{{name}}/compare/0.1.0...0.1.11. 头部声明声明遵循的规范第 1–2 行是文档的固定抬头# Change Log一级标题标明文档性质All notable changes to this project will be documented in this file.声明“本项目所有值得记录的变更都会写进此文件”这是 keepachangelog.com 的核心约定之一This change log follows the conventions of keepachangelog.com.显式声明遵循 Keep a Changelog 规范。Keep a Changelog 规范的核心原则包括为人类而非机器编写记录“值得注意的”变更而非全部提交记录区分Added新增、Changed更改、Deprecated弃用、Removed移除、Fixed修复、Security安全六类条目。模板正文恰好示范了其中四类Changed、Removed、Fixed、Added。2.## [Unreleased]未发布区## [Unreleased]是 keepachangelog 规范要求的固定小节用于记录“已合入主干但尚未发布”的变更。模板在此示例了一条### Changed条目## [Unreleased] ### Changed - Add a new arity to make-widget-async to provide a different widget shape.注意模板内容本身是虚构的示例make-widget-async之类目的是示范条目格式生成项目后应替换为真实变更。3.## [0.1.1] - {{date}}已发布版本的日期注入已发布版本的标题采用## [版本号] - 日期的格式。其中日期部分不是写死的而是 Mustache 变量{{date}}——渲染时会被替换为生成当天的日期ISO 8601 格式yyyy-MM-dd例如2026-09-28。该小节示范了三个子分类### Changed - Documentation on how to make the widgets. ### Removed - make-widget-sync - were all async, all the time. ### Fixed - Fixed widget maker to keep working when daylight savings switches over.4.## 0.1.0 - {{date}}首个版本注意0.1.0没有像[0.1.1]那样带方括号这是模板中一个轻微的格式不一致实际项目按 keepachangelog 规范应统一写作## [0.1.0] - {{date}}。该节示范了### Added分类### Added - Files from the new template. - Widget maker public API - make-widget-sync.5. 版本间比较链接Reference Links文件末尾使用 Markdown 引用式链接reference-style links维护两个版本比较地址[Unreleased]: https://source-host.site/your-name/{{name}}/compare/0.1.1...HEAD [0.1.1]: https://source-host.site/your-name/{{name}}/compare/0.1.0...0.1.1{{name}}会被替换为生成模板时指定的模板名source-host.site是占位主机名生成后需要改成真实代码托管平台如 GitLab/Gitee 等的项目地址该设计使变更日志中每个版本都能一键跳转到“两个版本之间的 diff”这是 keepachangelog 规范推荐的实践。三、Mustache 变量的注入机制{{date}}与{{name}}从哪来模板中的{{date}}、{{name}}并非手工替换而是由 Leiningen 的模板渲染管线在生成时自动完成。1. 数据来源template函数构建的 data mapsrc/leiningen/new/template.clj 中(let [render (t/renderer template) sym (symbol template-name) data {:name template-name :artifact-id (name sym) :group-prefix (if-let [group-id (namespace sym)] (str group-id /)) :sanitized (t/name-to-path (name sym)) :placeholder {{sanitized}} :year (t/year) :date (t/date)}] ... [CHANGELOG.md (render CHANGELOG.md data)])关键变量:name→ 模板名如my-template注入{{name}}用于版本比较链接:date→ 由t/date生成注入{{date}}:year→ 由t/year生成供 LICENSE 等文件使用:sanitized→ 由t/name-to-path转换的规范化名称用于源码目录命名。2. 日期与年份的底层实现src/leiningen/new/templates.clj 中(defn year Get the current year. Useful for setting copyright years and such. [] (.get (Calendar/getInstance) Calendar/YEAR)) (defn date Get the current date as a string in ISO8601 format. [] (let [df (java.text.SimpleDateFormat. yyyy-MM-dd)] ...))year通过java.util.Calendar获取当前年份用于 LICENSE 版权年份等场景date使用SimpleDateFormat输出 ISO 8601 格式yyyy-MM-dd的当天日期注入到版本标题的发布日期位置。3. 渲染器Mustache 模板查找与替换renderer函数templates.clj负责根据模板名定位resources/leiningen/new/模板名/目录下的模板文件并将 data map 中的键值渲染进 Mustache 占位符。生成 CHANGELOG.md 时渲染器找到resources/leiningen/new/template/CHANGELOG.md用上述 data 完成替换例如{{date}}→ 生成当天日期、{{name}}→ 用户传入的模板名。四、生成后的实际形态与使用方法1. 执行生成命令lein new template my-templateLeiningen 会打印Generating fresh lein new template project.随后在当前目录生成my-template/项目骨架其中的 CHANGELOG.md 已渲染完成例如## [0.1.1] - 2026-09-28 ### Changed - Documentation on how to make the widgets. ... [Unreleased]: https://source-host.site/your-name/my-template/compare/0.1.1...HEAD2. 模板项目内的维护建议生成骨架后应把占位内容替换为真实信息删除或改写[Unreleased]下的示例条目改为本项目真实未发布变更将source-host.site/your-name/替换为实际代码托管仓库地址发布新版本时按语义化版本规范SemVer在## [Unreleased]上方新增## [x.y.z] - 发布日期小节并把[Unreleased]的比较链接更新为最新版本...HEAD保持Added / Changed / Removed / Fixed等分类与 keepachangelog 约定一致。3. 同源模板的横向对比本仓库中default 模板、app 模板、plugin 模板 的 CHANGELOG.md 与 template 版本结构完全一致仅比较链接中的占位主机名写法略有差异说明变更日志骨架在所有lein new产物中是统一标配真正不同的是各模板的project.clj与源码结构例如模板项目自身通过 project.clj 中的:eval-in-leiningen true声明其在 Leiningen 进程内求值这是模板代码能直接调用 Leiningen 内部 API 的关键。五、总结resources/leiningen/new/template/CHANGELOG.md虽只有 24 行却是 Leiningen 模板生成体系中信息密度很高的一份骨架它同时承担了“规范示范”Keep a Changelog 的章节与分类约定、“变量示例”{{date}}、{{name}}两个 Mustache 占位符与“发布流程模板”Unreleased → 版本标题 → 比较链接三重职责。理解它的渲染机制就能举一反三——lein new template生成的每个文件本质上都是“Mustache 骨架 data map 注入”的产物修改模板时只需在 template.clj 的 data map 中扩展键、在对应模板文件中新增{{键名}}占位符即可。赞分享构建工具CLI【免费下载链接】leiningenMoved to Codeberg; this is a temporary convenience mirror项目地址https://gitcode.com/gh_mirrors/le/leiningen点击查看免费下载相关推荐深入解析git-cliff的Keep a Changelog配置模板深入解析git cliff的Keep a Changelog配置模板 git cliff是一个强大的变更日志生成工具它能够根据Git提交历史自动生成符合规范的CLI开发工具如何规范管理项目变更日志Keep a Changelog 完全指南如何规范管理项目变更日志Keep a Changelog 完全指南 在软件开发过程中 版本变更日志管理 是项目维护的关键环节。Keep a Changelo文档web3.js 仓库 CHANGELOG 规范与实践基于 Keep a Changelog 与 SemVer 的自动化维护指南web3.js 仓库 CHANGELOG 规范与实践基于 Keep a Changelog 与 SemVer 的自动化维护指南 本篇技术指南以 web3.js区块链Web3上一篇实战指南轻松实现跨平台键鼠共享的智能解决方案下一篇React-Feather TypeScript集成指南完美类型支持与最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考