🚀 发布策略
Semantic Versioning、Changelog 自动生成、GitHub Release 页面——版本发布是你和用户之间的契约
📐 Semantic Versioning 详解
SemVer 是开源世界最广泛使用的版本规范。格式：MAJOR.MINOR.PATCH
1
MAJOR（主版本）
不兼容的 API 变更
⚠️ 破坏性变更
0
MINOR（次版本）
向后兼容的新功能
✅ 新增功能
0
PATCH（修订版）
向后兼容的 Bug 修复
🐛 修复问题
# 版本号演变示例
1.0.0 → 初始稳定版
1.0.1 → 修复了一个 Bug (PATCH)
1.1.0 → 新增了导出功能 (MINOR)
2.0.0 → 重构了 API，旧代码不兼容 (MAJOR)
# 0.x.x 是"初始开发阶段"
# 0.x 的任何变更都可能是破坏性的
# 1.0.0 才意味着"API 已稳定"
# Pre-release 标签
1.0.0-alpha.1 — 内部测试
1.0.0-beta.2 — 公开测试
1.0.0-rc.1 — 候选发布
📝 Changelog 自动生成
手动写 Changelog 是反人类的工作。Conventional Commits + 自动化工具可以完全消除这个负担。
# .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
- name: Release
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
run: npx semantic-release
# semantic-release 配置
# .releaserc.yml
{
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/changelog",
"@semantic-release/npm",
"@semantic-release/github",
"@semantic-release/git"
]
}
Conventional Commits 格式
# 格式: type(scope): subject
feat(auth): 添加 OAuth2 登录支持 → MINOR 版本
fix(api): 修复分页参数解析错误 → PATCH 版本
feat!: 重构数据库查询 API → MAJOR 版本（! 表示破坏性变更）
docs: 更新 README 安装说明 → 不触发版本发布
perf(query): 优化列表查询性能 30% → PATCH 版本
# scope 是可选的，但推荐用于大型项目
# subject 不超过 72 字符，不用句号结尾
# body 可以用多行详细描述
🏷️ GitHub Release 页面最佳实践
GitHub Release 页面是你向用户传达"为什么要升级"的地方。好的 Release Note 能上 Hacker News 头条。
## 🎉 v2.0.0 — The Agent Edition
### 💥 Breaking Changes
- `createAgent()` 现在需要 `config` 参数 (#456)
- 移除了 `agent.run()` — 请使用 `agent.execute()` (#478)
### ✨ New Features
- **Agent Chain**: 链式调用多个 Agent (@contributor1, #501)
- **Streaming Output**: 支持流式输出中间结果 (#498)
- **Tool Registry**: 动态注册和发现工具 (#512)
### 🐛 Bug Fixes
- 修复长时间运行时内存泄漏 (#489)
- 修复并发请求时竞态条件 (#495)
### 📚 Documentation
- 新增 Agent Chain 教程
- 更新 API 参考
### ⬆️ Upgrade Guide
\`\`\`diff
- const agent = createAgent();
+ const agent = createAgent({ model: 'gpt-4' });
- agent.run(task);
+ agent.execute(task);
\`\`\`
**Full Changelog**: https://github.com/user/repo/compare/v1.9.0...v2.0.0
Release Note 怎么写才能上 Hacker News
| 要素 | 为什么重要 | 案例 |
|---|
| Breaking Changes 放最前 | 用户最关心"我会不会挂" | React 18 的 Concurrent Mode |
| Upgrade Guide | 降低升级门槛 | Next.js 13 App Router 迁移指南 |
| 贡献者致谢 | 激励社区继续贡献 | 用 @mention 标注每个贡献者 |
| 对比链接 | 技术用户想看具体改了什么 | Full Changelog 链接 |
| 视觉元素 | Hacker News 只有文字，用 emoji 做视觉锚点 | 🎉✨🐛📚 |
📦 npm 发布自动化
# package.json 发布配置
{
"name": "your-package",
"version": "0.0.0-development", // semantic-release 管理
"publishConfig": {
"access": "public",
"registry": "https://registry.npmjs.org/"
},
"files": [
"dist",
"README.md",
"LICENSE"
],
"scripts": {
"prepublishOnly": "npm run build",
"release": "semantic-release"
}
}
# .npmrc — 确保正确的 registry
registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=${NPM_TOKEN}
🔄 发布节奏建议
| 项目阶段 | 推荐节奏 | 理由 |
|---|
| 0.x 初始开发 | 每周 1-2 次 | 快速迭代，用户预期不稳定 |
| 1.0 稳定版 | 每 2-4 周 | 稳定节奏，用户可预期 |
| 成熟期 | 每月 1 次 | 大版本 3-6 月一次，小版本每月 |
| 安全修复 | 立即发布 | 不跟节奏，安全漏洞优先 |
💡 Next.js 的发布节奏
Next.js 采用 "Canary → RC → Stable" 三段式发布：每日自动发布 Canary 版本 → 功能稳定后发布 RC → RC 一周无重大问题则发布 Stable。这种模式让用户可以按风险承受力选择跟进速度。Vercel 内部项目直接用 Canary，外部生产用 Stable。
🔗 相关专题
🤝 CONTRIBUTING.md · 🔥 病毒式增长 · ⚖️ 治理模型 · 📢 返回首页