📋 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 |
Fixed | Bug 修复 | 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,让社区知道"我们还活着"。
🔗 相关专题
🚀 发布策略 · ✏️ 写作风格 · ✍️ 返回首页