Agentic Awesome Skills 实战：用 Changelog Automation 技能自动化变更日志、发布说明与版本管理

Agentic Awesome Skills 实战用 Changelog Automation 技能自动化变更日志、发布说明与版本管理【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills本指南以 changelog-automation 技能 为骨架完整讲解 Keep a Changelog 格式、Conventional Commits 约定、语义化版本Semantic Versioning三者如何协同并给出 commitlint Husky、standard-version、semantic-release、GitHub Actions、git-cliff、commitizen 六套可直接落地的自动化方案与发布说明模板。读完本文你将能在自己的项目中搭建提交规范化 → 版本自动提升 → 变更日志自动生成 → 发布说明自动发布的完整流水线并用 仓库自身的 CHANGELOG.md 验证这套标准的真实应用形态。技能定位何时该用、何时不该用在 Agentic Awesome Skills 目录中changelog-automation被收录于 plugins/agentic-awesome-skills-claude/skills/changelog-automation/SKILL.md其在 data/catalog.json 中的能力描述为Automate changelog generation from commits, PRs, and releases following Keep a Changelog format. Use when setting up release workflows, generating release notes, or standardizing commit conventions.元数据声明risk: critical、source: community意味着该技能涉及可能影响发布流程的关键操作执行前需要充分的环境验证。适用场景Use this skill when搭建自动化变更日志生成流程落地 Conventional Commits 提交规范创建发布说明Release Notes工作流统一提交信息格式管理语义化版本号。不适用场景Do not use this skill when项目没有发布流程或版本管理只需要一次性的人工发布说明提交历史不可用或不可靠说明自动化工具完全依赖 git 历史与 tag历史混乱时生成结果无意义。核心操作指令Instructions先选定变更日志格式与版本策略再通过提交约定或标签规则强制执行规范随后配置工具生成并发布说明最后人工复核输出的准确性、完整性与措辞。需要更详细的模式与示例时打开 implementation-playbook.md。安全约束Safety发布说明中严禁暴露密钥或仅内部可见的细节——变更日志往往直接对公众可见这是唯一被技能明确标记的红线。三大基础标准Keep a Changelog × Conventional Commits × SemVer自动化的前提是机器可读的输入这三套标准分别解决文档形态、提交信息与版本号规则三个问题。1. Keep a Changelog 格式仓库根目录的 CHANGELOG.md 就是该格式的活样本顶部声明格式与版本遵循标准随后按## [版本号] - 日期组织条目每个版本内用### Added / Changed / Fixed等小节分类最后在文件底部维护用于生成对比链接的引用锚点。完整模板如下来自 implementation-playbook.md# Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ### Added - New feature X ## [1.2.0] - 2024-01-15 ### Added - User profile avatars - Dark mode support ### Changed - Improved loading performance by 40% ### Deprecated - Old authentication API (use v2) ### Removed - Legacy payment gateway ### Fixed - Login timeout issue (#123) ### Security - Updated dependencies for CVE-2024-1234 [Unreleased]: https://github.com/user/repo/compare/v1.2.0...HEAD [1.2.0]: https://github.com/user/repo/compare/v1.1.0...v1.2.0小节通常包含Added、Changed、Deprecated、Removed、Fixed、Security六类底部锚点让 GitHub 等平台能自动渲染版本对比链接。2. Conventional Commits 提交约定提交信息采用统一结构type[optional scope]: description [optional body] [optional footer(s)]各类型与变更日志小节的映射关系如下表Type含义Changelog 小节feat新功能Addedfix缺陷修复Fixeddocs文档通常排除style格式调整通常排除refactor代码重构Changedperf性能优化Changedtest测试通常排除chore杂项维护通常排除ciCI 变更通常排除build构建系统通常排除revert回滚提交Removed3. Semantic Versioning语义化版本MAJOR.MINOR.PATCH MAJOR: Breaking changes (feat! 或 BREAKING CHANGE footer) MINOR: New features (feat) PATCH: Bug fixes (fix)三者联动关系提交类型决定版本增量版本增量决定 changelog 分组changelog 分组决定发布说明内容——这正是自动化能成立的根本原因。提交规范落地commitlint Husky 强制校验在提交发生前就拦截不规范信息是最便宜的治理手段。Node.js 生态的标准组合是 commitlint校验规则 Huskygit 钩子注入# 安装工具 npm install -D commitlint/cli commitlint/config-conventional npm install -D husky npm install -D standard-version # 或 npm install -D semantic-release # 配置 commitlint cat commitlint.config.js EOF module.exports { extends: [commitlint/config-conventional], rules: { type-enum: [ 2, always, [ feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert, ], ], subject-case: [2, never, [start-case, pascal-case, upper-case]], subject-max-length: [2, always, 72], }, }; EOF # 初始化 husky 并在 commit-msg 钩子中执行校验 npx husky init echo npx --no -- commitlint --edit \$1 .husky/commit-msg配置要点说明type-enum允许的类型白名单与上表保持一致防止featu、fixx这类拼写错误混入subject-case禁止Start-case / Pascal-case / Upper-case风格的标题如Add Login强制小写开头保证 changelog 自动生成的句子风格统一subject-max-length主题行不超过 72 字符兼容git log的默认展示宽度也避免生成工具输出过长单行条目。版本管理与变更日志生成standard-version半自动standard-version读取 Conventional Commits 自动计算下一个版本号、更新 CHANGELOG.md 并打 tag适合希望保留人工触发、自动计算节奏的团队。.versionrc.js 配置// .versionrc.js module.exports { types: [ { type: feat, section: Features }, { type: fix, section: Bug Fixes }, { type: perf, section: Performance Improvements }, { type: revert, section: Reverts }, { type: docs, section: Documentation, hidden: true }, { type: style, section: Styles, hidden: true }, { type: chore, section: Miscellaneous, hidden: true }, { type: refactor, section: Code Refactoring, hidden: true }, { type: test, section: Tests, hidden: true }, { type: build, section: Build System, hidden: true }, { type: ci, section: CI/CD, hidden: true }, ], commitUrlFormat: {{host}}/{{owner}}/{{repository}}/commit/{{hash}}, compareUrlFormat: {{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}, issueUrlFormat: {{host}}/{{owner}}/{{repository}}/issues/{{id}}, userUrlFormat: {{host}}/{{user}}, releaseCommitMessageFormat: chore(release): {{currentTag}}, scripts: { prebump: echo Running prebump, postbump: echo Running postbump, prechangelog: echo Running prechangelog, postchangelog: echo Running postchangelog, }, };要点解析types[].hidden: true该类型仍被解析但不会出现在生成的 changelog 中如 docs、chore避免噪音commitUrlFormat / compareUrlFormat / issueUrlFormat控制生成的链接模板默认使用{{host}}、{{owner}}、{{repository}}占位符适配不同托管平台releaseCommitMessageFormat标准-版本自身发布的提交统一为chore(release): x.y.z恰好对应 git-cliff 配置里^chore\(release\)被skip的场景见下文scripts在 bump 前后、changelog 生成前后挂载钩子可插入构建、测试或通知逻辑。package.json 脚本{ scripts: { release: standard-version, release:minor: standard-version --release-as minor, release:major: standard-version --release-as major, release:patch: standard-version --release-as patch, release:dry: standard-version --dry-run } }--release-as用于显式指定版本增量跳过基于提交的自动判断--dry-run可先预览将要发生的版本号、changelog 改动和 tag是发布前自检的关键手段。全自动发布semantic-release GitHub Actionssemantic-release将分析提交 → 决定版本 → 生成发布说明 → 更新 changelog → 发布 npm 包 → 创建 GitHub Release → 提交回仓库全流程自动化适合对发布节奏有强纪律要求、且 CI 基础设施稳定的团队。release.config.js 配置// release.config.js module.exports { branches: [ main, { name: beta, prerelease: true }, { name: alpha, prerelease: true }, ], plugins: [ semantic-release/commit-analyzer, semantic-release/release-notes-generator, [ semantic-release/changelog, { changelogFile: CHANGELOG.md, }, ], [ semantic-release/npm, { npmPublish: true, }, ], [ semantic-release/github, { assets: [dist/**/*.js, dist/**/*.css], }, ], [ semantic-release/git, { assets: [CHANGELOG.md, package.json], message: chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}, }, ], ], };要点解析branches除main外可配置beta、alpha预发布分支各自的提交会生成x.y.z-beta.n版本插件顺序即执行管线commit-analyzer分析提交决定增量→release-notes-generator生成说明→changelog写文件→npm发布包→github建 Release 并附构建产物→git把 CHANGELOG.md 与 package.json 的改动提交回去[skip ci]是防止 release 提交再次触发 CI 的循环惯例。配套 CI 工作流# .github/workflows/release.yml name: Release on: push: branches: [main] workflow_dispatch: inputs: release_type: description: Release type required: true default: patch type: choice options: - patch - minor - major permissions: contents: write pull-requests: write jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 token: ${{ secrets.GITHUB_TOKEN }} - uses: actions/setup-nodev4 with: node-version: 20 cache: npm - run: npm ci - name: Configure Git run: | git config user.name github-actions[bot] git config user.email github-actions[bot]users.noreply.github.com - name: Run semantic-release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }} run: npx semantic-release # Alternative: manual release with standard-version manual-release: if: github.event_name workflow_dispatch runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm ci - name: Configure Git run: | git config user.name github-actions[bot] git config user.email github-actions[bot]users.noreply.github.com - name: Bump version and generate changelog run: npx standard-version --release-as ${{ inputs.release_type }} - name: Push changes run: git push --follow-tags origin main - name: Create GitHub Release uses: softprops/action-gh-releasev1 with: tag_name: ${{ steps.version.outputs.tag }} body_path: CHANGELOG.md generate_release_notes: true关键细节fetch-depth: 0必须保留完整提交历史否则提交分析器无法正确计算版本增量workflow_dispatch提供patch/minor/major手动选择配合standard-version --release-as实现手动决策 自动落地的混合模式softprops/action-gh-release的generate_release_notes: true会混合生成 GitHub 自动 Release Notes 与 CHANGELOG 内容。高性能替代git-cliffRust与 commitizenPython非 Node.js 技术栈同样有成熟方案。git-cliffRust 编写、速度快、模板引擎强大通过cliff.toml配置使用 Tera 模板控制输出且内置 GitHub PR 链接提取能力# cliff.toml [changelog] header # Changelog All notable changes to this project will be documented in this file. body {% if version %}\ ## [{{ version | trim_start_matches(patv) }}] - {{ timestamp | date(format%Y-%m-%d) }} {% else %}\ ## [Unreleased] {% endif %}\ {% for group, commits in commits | group_by(attributegroup) %} ### {{ group | upper_first }} {% for commit in commits %} - {% if commit.scope %}**{{ commit.scope }}:** {% endif %}\ {{ commit.message | upper_first }}\ {% if commit.github.pr_number %} ([#{{ commit.github.pr_number }}](https://github.com/owner/repo/pull/{{ commit.github.pr_number }})){% endif %}\ {% endfor %} {% endfor %} footer {% for release in releases -%} {% if release.version -%} {% if release.previous.version -%} [{{ release.version | trim_start_matches(patv) }}]: \ https://github.com/owner/repo/compare/{{ release.previous.version }}...{{ release.version }} {% endif -%} {% else -%} [unreleased]: https://github.com/owner/repo/compare/{{ release.previous.version }}...HEAD {% endif -%} {% endfor %} trim true [git] conventional_commits true filter_unconventional true split_commits false commit_parsers [ { message ^feat, group Features }, { message ^fix, group Bug Fixes }, { message ^doc, group Documentation }, { message ^perf, group Performance }, { message ^refactor, group Refactoring }, { message ^style, group Styling }, { message ^test, group Testing }, { message ^chore\\(release\\), skip true }, { message ^chore, group Miscellaneous }, ] filter_commits false tag_pattern v[0-9]* skip_tags ignore_tags topo_order false sort_commits oldest [github] owner owner repo repo模板与解析器的配合逻辑body中按commit_parsers分组的group迭代输出小节^chore\(release\)的skip true精确跳过 release 提交自身避免 changelog 里出现发布了发布的循环条目trim_start_matches(patv)负责去掉 tag 前缀再展示版本号。常用命令# 生成完整 changelog git cliff -o CHANGELOG.md # 指定范围生成 git cliff v1.0.0..v2.0.0 -o CHANGELOG.md # 只预览 Unreleased 部分不写文件 git cliff --unreleased --dry-runcommitizenPython交互式提交 版本提升# pyproject.toml [tool.commitizen] name cz_conventional_commits version 1.0.0 version_files [ pyproject.toml:version, src/__init__.py:__version__, ] tag_format v$version update_changelog_on_bump true changelog_incremental true changelog_start_rev v0.1.0 [tool.commitizen.customize] message_template {{change_type}}{% if scope %}({{scope}}){% endif %}: {{message}} schema type(scope): subject schema_pattern ^(feat|fix|docs|style|refactor|perf|test|chore)(\\(\\w\\))?:\\s.* bump_pattern ^(feat|fix|perf|refactor) bump_map {feat MINOR, fix PATCH, perf PATCH, refactor PATCH}# 安装 pip install commitizen # 交互式创建规范提交 cz commit # 提升版本并更新 changelog cz bump --changelog # 校验某段提交历史是否符合规范 cz check --rev-range HEAD~5..HEADPython 项目的关键配置点version_files声明需要同步更新版本号的文件及定位模式pyproject.toml:version、src/__init__.py:__version__bump 时一并改写bump_pattern / bump_map自定义哪些提交类型触发哪档版本增量的规则如refactor也触发 PATCHchangelog_incremental true只追加自上次 tag 以来的增量避免整文件重写丢失人工润色内容。发布说明模板GitHub Release 与内部 Release Notes自动生成的 changelog 适合存档面向读者的发布说明则需要重组信息层级。GitHub Release 模板Go template 语法## Whats Changed ### Features {{ range .Features }} - {{ .Title }} by {{ .Author }} in #{{ .PR }} {{ end }} ### Bug Fixes {{ range .Fixes }} - {{ .Title }} by {{ .Author }} in #{{ .PR }} {{ end }} ### Documentation {{ range .Docs }} - {{ .Title }} by {{ .Author }} in #{{ .PR }} {{ end }} ### Maintenance {{ range .Chores }} - {{ .Title }} by {{ .Author }} in #{{ .PR }} {{ end }} ## New Contributors {{ range .NewContributors }} - {{ .Username }} made their first contribution in #{{ .PR }} {{ end }} **Full Changelog**: https://github.com/owner/repo/compare/v{{ .Previous }}...v{{ .Current }}突出作者归属 PR 链接 新贡献者致谢适用于开源项目对外发布。内部 Release Notes 模板# Release v2.1.0 - January 15, 2024 ## Summary This release introduces dark mode support and improves checkout performance by 40%. It also includes important security updates. ## Highlights ### Dark Mode Users can now switch to dark mode from settings. The preference is automatically saved and synced across devices. ### ⚡ Performance - Checkout flow is 40% faster - Reduced bundle size by 15% ## Breaking Changes None in this release. ## Upgrade Guide No special steps required. Standard deployment process applies. ## Known Issues - Dark mode may flicker on initial load (fix scheduled for v2.1.1) ## Dependencies Updated | Package | From | To | Reason | |---------|------|-----|--------| | react | 18.2.0 | 18.3.0 | Performance improvements | | lodash | 4.17.20 | 4.17.21 | Security patch |内部模板强调 Summary摘要、Highlights亮点、Breaking Changes破坏性变更、Upgrade Guide升级指引、Known Issues已知问题与依赖更新表——这些恰恰是 changelog 不会自动承载的信息需要在生成结果上人工补齐。提交信息实战示例规范的提交信息是上述所有工具的输入基础参考以下分级示例# 带 scope 的功能提交 feat(auth): add OAuth2 support for Google login # 带 issue 引用的缺陷修复 fix(checkout): resolve race condition in payment processing Closes #123 # 破坏性变更! 标记 BREAKING CHANGE footer feat(api)!: change user endpoint response format BREAKING CHANGE: The user endpoint now returns userId instead of id. Migration guide: Update all API consumers to use the new field name. # 多段 body 的复杂提交 fix(database): handle connection timeouts gracefully Previously, connection timeouts would cause the entire request to fail without retry. This change implements exponential backoff with up to 3 retries before failing. The timeout threshold has been increased from 5s to 10s based on p99 latency analysis. Fixes #456 Reviewed-by: alice注意细节破坏性变更用!feat(api)!:与BREAKING CHANGE:footer 双标记这样 commit-analyzer 才能正确识别 MAJOR 增量footer 支持Closes、Fixes、Reviewed-by等多行元数据自动化工具可据此关联 issue 与评审人。最佳实践清单Dos应当遵循 Conventional Commits——这是所有自动化的前提提交信息清晰完整未来检索时能看懂引用 issue 编号把提交与工单关联团队内统一 scope 使用规范自动化发布流程减少人工操作错误。Donts避免不要混合多个逻辑变更到同一次提交不要跳过提交校验commitlint 应进入本地钩子与 CI 双重防线不要手工编辑自动生成的 changelog下次生成会被覆盖保留人工编辑应放到发布说明层不要遗漏破坏性变更标记!或 footer否则 MAJOR 版本不会被正确触发不要在 CI 中忽略提交校验。在 Agentic Awesome Skills 中继续探索本技能是 AAS 目录中release相关工作流的一环与本主题相关的更多实践材料包括changelog-updates 技能面向开发者的发布说明撰写与破坏性变更通告app-store-changelog 技能应用商店场景的变更说明技能的详细模式、模板与全部代码示例集中维护在 implementation-playbook.md仓库根目录 CHANGELOG.md8,000 行可作为 Keep a Changelog 格式在大规模真实项目中的完整范例其条目结构、版本锚点与引用链接写法都值得对照研读。局限性与使用前提本技能仅在任务与上述范围明确匹配时使用不应套用于无关需求自动化输出不能替代针对具体环境的验证、测试与专家评审——发布前务必在 dry-run 模式下预览结果若所需的输入、权限、安全边界或成功标准缺失应停止执行并向用户澄清而不是贸然推进版本提升或对外发布。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,445 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考