📋 Changelog

Keep a Changelog 规范、Conventional Commits 自动生成、Release Tweet/Thread 模板——让用户知道"为什么要升级"

📖 Keep a Changelog 规范

Keep a Changelog(keepachangelog.com)是 Changelog 格式的事实标准。核心理念:Changelog 是给人读的,不是给机器读的 git log。

# CHANGELOG.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). ## [2.1.0] - 2024-03-15 ### Added - `agent.chain()` method for chaining multiple agents (#501) - Streaming output support for long-running tasks (#498) - Tool registry for dynamic tool discovery (#512) ### Changed - Improved error messages for authentication failures (#523) - Updated default model from gpt-3.5 to gpt-4o-mini (#530) ### Deprecated - `agent.run()` is deprecated, use `agent.execute()` instead (#478) Will be removed in v3.0.0 ### Removed - Dropped support for Node.js 16 (#540) ### Fixed - Memory leak in long-running sessions (#489) - Race condition in concurrent tool calls (#495) ### Security - Updated `lodash` to fix prototype pollution (CVE-2024-XXXX) (#555) ## [2.0.0] - 2024-01-20 ### Breaking Changes - `createAgent()` now requires a `config` parameter (#456) - Removed `agent.run()` — use `agent.execute()` (#478) [2.1.0]: https://github.com/user/repo/compare/v2.0.0...v2.1.0 [2.0.0]: https://github.com/user/repo/compare/v1.9.0...v2.0.0

六大分类详解

分类含义SemVer 影响
Added新功能MINOR (+1)
Changed已有功能的变更MINOR 或 PATCH
Deprecated即将移除的功能MINOR
Removed已移除的功能MAJOR
FixedBug 修复PATCH
Security安全修复PATCH(紧急)

🤖 Conventional Commits → 自动生成 Changelog

# conventional-changelog 自动生成 # 安装 npm install -D conventional-changelog conventional-changelog-cli # 手动生成 npx conventional-changelog -p angular -i CHANGELOG.md -s # package.json 脚本 { "scripts": { "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s", "version": "npm run changelog && git add CHANGELOG.md" } } # 完整自动化:semantic-release # .releaserc.json { "branches": ["main"], "plugins": [ ["@semantic-release/commit-analyzer", { "preset": "conventionalcommits", "releaseRules": [ { "type": "feat", "release": "minor" }, { "type": "fix", "release": "patch" }, { "type": "perf", "release": "patch" }, { "type": "feat", "scope": "breaking", "release": "major" }, { "breaking": true, "release": "major" } ] }], ["@semantic-release/release-notes-generator", { "preset": "conventionalcommits", "writerOpts": { "groupBy": "type", "commitGroupsSort": "title", "commitsSort": "scope" } }], "@semantic-release/changelog", "@semantic-release/npm", "@semantic-release/github", ["@semantic-release/git", { "assets": ["CHANGELOG.md", "package.json"], "message": "chore(release): ${nextRelease.version}" }] ] } # GitHub Actions 完整配置 # .github/workflows/release.yml name: Release on: push: branches: [main] jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-node@v4 with: { node-version: 20 } - run: npm ci - run: npx semantic-release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

🐦 Release Tweet/Thread 模板

# 模板 1: 简短版(单个 Tweet) 🚀 [Project] v2.1 is out! ✨ New: Agent chaining, streaming output 🐛 Fixed: Memory leak in long sessions ⚡ Default model upgraded to gpt-4o-mini Upgrade: npm i project@latest Changelog: https://github.com/... #AI #OpenSource #DevTools --- # 模板 2: Thread 版(大版本发布) 1/ 🎉 [Project] v2.0 — The Agent Edition is here! After 6 months of development, we're excited to share what's new. TL;DR: Everything is faster, more reliable, and easier to use. 2/ 💥 Breaking Changes - `createAgent()` now requires config - `agent.run()` → `agent.execute()` Don't worry — we have a migration guide: https://docs.project.dev/migration/v2 3/ ✨ Highlights 🔹 Agent Chain: Link multiple agents in sequence 🔹 Streaming: See results as they happen 🔹 Tool Registry: Discover & install tools dynamically 4/ 🎬 See it in action [Demo GIF] 5/ 📊 By the numbers - 500+ commits - 50+ contributors - 3x faster agent execution - 60% less memory usage 6/ 🙏 Thank you to our amazing community @contributor1 @contributor2 @contributor3 and 47 more contributors! 7/ Upgrade now: npm i project@latest What are you building with v2? Reply below! 👇

📡 用户可订阅的更新

# 方案 1: GitHub Releases RSS # 用户可以订阅你的 Release RSS Feed: https://github.com/user/repo/releases.atom # 方案 2: 邮件通知 (通过 GitHub Actions) # .github/workflows/notify.yml name: Release Notify on: release: types: [published] jobs: notify: runs-on: ubuntu-latest steps: - name: Send email via Resend uses: resend/resend-action@v1 with: api-key: ${{ secrets.RESEND_API_KEY }} from: releases@project.dev to: subscribers-list subject: "🚀 ${{ github.event.release.tag_name }} Released" html: |

🎉 New Release: ${{ github.event.release.tag_name }}

${{ github.event.release.body }} - name: Post to Discord uses: discord-actions/message@v1 with: webhook-url: ${{ secrets.DISCORD_WEBHOOK }} message: | 🚀 **New Release: ${{ github.event.release.tag_name }}** ${{ github.event.release.body }} ${ github.event.release.html_url }} # 方案 3: changelog.com (SaaS) # 专业 Changelog 即服务 # 自动追踪 GitHub Release → 生成美观的更新页面 # 方案 4: 自建订阅系统 # 用 KV 存储订阅者列表 + Edge Function 发送

💡 Changelog 的隐性价值

好的 Changelog 不仅告诉用户"改了什么",更传递"项目在活跃维护"的信号。一个 3 个月没更新的 Changelog 比一个 3 个月没更新的 README 更让人担心——它意味着项目可能死了。建议即使没有大版本,也定期发布 PATCH 版本的 Changelog,让社区知道"我们还活着"。

🔗 相关专题

🚀 发布策略 · ✏️ 写作风格 · ✍️ 返回首页