Back to Details

changelog-setup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Changelog Setup

变更日志搭建指南

Complete changelog and release notes infrastructure for a project that doesn't have one.
为尚无变更日志的项目搭建完整的变更日志与发布说明基础设施。

When to Use

适用场景

Project has no release infrastructure. Starting fresh.
项目暂无发布相关基础设施，需从零开始搭建。

Workflow

工作流

This workflow installs components in sequence:
本工作流将按顺序安装以下组件：

1. Assess (confirm greenfield)

1. 评估（确认全新项目状态）

Run 
changelog-assess
to confirm this is actually greenfield. If partial infrastructure exists, consider audit/reconcile instead.
运行
changelog-assess
命令确认项目确实是全新状态。若已有部分基础设施，建议使用审计/协调流程替代。

2. Install Dependencies

2. 安装依赖

bash
pnpm add -D semantic-release \
  @semantic-release/changelog \
  @semantic-release/git \
  @semantic-release/github \
  @commitlint/cli \
  @commitlint/config-conventional
bash
pnpm add -D semantic-release \
  @semantic-release/changelog \
  @semantic-release/git \
  @semantic-release/github \
  @commitlint/cli \
  @commitlint/config-conventional

3. Configure semantic-release

3. 配置semantic-release

Create 
.releaserc.js
:
javascript
// See references/semantic-release-config.md for full config
module.exports = {
  branches: ['main', 'master'],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    ['@semantic-release/changelog', {
      changelogFile: 'CHANGELOG.md',
    }],
    '@semantic-release/npm', // or remove if not publishing to npm
    ['@semantic-release/git', {
      assets: ['CHANGELOG.md', 'package.json'],
      message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
    }],
    '@semantic-release/github',
  ],
};
创建
.releaserc.js
文件：
javascript
// 完整配置请参考references/semantic-release-config.md
module.exports = {
  branches: ['main', 'master'],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    ['@semantic-release/changelog', {
      changelogFile: 'CHANGELOG.md',
    }],
    '@semantic-release/npm', // 若无需发布至npm可移除
    ['@semantic-release/git', {
      assets: ['CHANGELOG.md', 'package.json'],
      message: 'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',
    }],
    '@semantic-release/github',
  ],
};

4. Configure commitlint

4. 配置commitlint

Create 
commitlint.config.js
:
javascript
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'build', 'ci', 'chore', 'revert'
    ]],
    'subject-case': [2, 'always', 'lower-case'],
    'header-max-length': [2, 'always', 100],
  },
};
创建
commitlint.config.js
文件：
javascript
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor',
      'perf', 'test', 'build', 'ci', 'chore', 'revert'
    ]],
    'subject-case': [2, 'always', 'lower-case'],
    'header-max-length': [2, 'always', 100],
  },
};

5. Add Lefthook Hook

5. 添加Lefthook钩子

Update 
lefthook.yml
(create if doesn't exist):
yaml
commit-msg:
  commands:
    commitlint:
      run: pnpm commitlint --edit {1}
Run 
pnpm lefthook install
to activate.
更新
lefthook.yml
文件（若不存在则创建）：
yaml
commit-msg:
  commands:
    commitlint:
      run: pnpm commitlint --edit {1}
运行
pnpm lefthook install
激活钩子。

6. Create GitHub Actions Workflow

6. 创建GitHub Actions工作流

Create 
.github/workflows/release.yml
:
yaml
undefined
创建
.github/workflows/release.yml
文件：
yaml
undefined

See references/github-actions-release.md for full workflow

完整工作流请参考references/github-actions-release.md

name: Release
on: push: branches: [main, master]
permissions: contents: write issues: write pull-requests: write
jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 persist-credentials: false
  - uses: pnpm/action-setup@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 22
      cache: 'pnpm'

  - run: pnpm install --frozen-lockfile
  - run: pnpm build

  - name: Release
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
    run: pnpm semantic-release
synthesize-notes: needs: release if: needs.release.outputs.new_release_published == 'true' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Synthesize Release Notes env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }} run: | # See references/llm-synthesis.md for script node scripts/synthesize-release-notes.mjs
undefined
name: Release
on: push: branches: [main, master]
permissions: contents: write issues: write pull-requests: write
jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 persist-credentials: false
  - uses: pnpm/action-setup@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 22
      cache: 'pnpm'

  - run: pnpm install --frozen-lockfile
  - run: pnpm build

  - name: Release
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
    run: pnpm semantic-release
synthesize-notes: needs: release if: needs.release.outputs.new_release_published == 'true' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Synthesize Release Notes env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }} run: | # 脚本详情请参考references/llm-synthesis.md node scripts/synthesize-release-notes.mjs
undefined

7. Configure LLM Synthesis

7. 配置LLM合成功能

Create 
.release-notes-config.yml
:
yaml
undefined
创建
.release-notes-config.yml
文件：
yaml
undefined

App-specific configuration for release notes synthesis

发布说明合成的应用专属配置

app_name: "Your App Name" personality: "professional, friendly, confident" audience: "non-technical users"
tone_examples:
  • "We made it faster to find what you need"
  • "Your dashboard now shows more detail"
avoid:
  • Technical jargon (API, SDK, webhook, etc.)
  • Git commit references
  • Internal code names
  • Version numbers in descriptions
categories: feat: "New Features" fix: "Improvements" perf: "Performance" chore: "Behind the Scenes" refactor: "Behind the Scenes" docs: "Documentation" test: "Quality"

Create `scripts/synthesize-release-notes.mjs`:
(See `references/llm-synthesis-script.md` for full implementation)
app_name: "你的应用名称" personality: "专业、友好、自信" audience: "非技术用户"
tone_examples:
  • "我们优化了内容查找速度"
  • "你的仪表盘现在展示更多细节"
avoid:
  • 技术术语（API、SDK、webhook等）
  • Git提交引用
  • 内部代码名称
  • 描述中出现版本号
categories: feat: "新功能" fix: "优化改进" perf: "性能提升" chore: "幕后更新" refactor: "幕后更新" docs: "文档更新" test: "质量保障"

创建`scripts/synthesize-release-notes.mjs`文件：
（完整实现请参考`references/llm-synthesis-script.md`）

8. Scaffold Public Changelog Page

8. 搭建公开变更日志页面

Run 
changelog-page
to scaffold:
  • /app/changelog/page.tsx
    - Main page component
  • /app/changelog.xml/route.ts
    - RSS feed
  • /lib/github-releases.ts
    - GitHub API client
运行
changelog-page
命令搭建以下内容：
  • /app/changelog/page.tsx
    - 主页面组件
  • /app/changelog.xml/route.ts
    - RSS订阅源
  • /lib/github-releases.ts
    - GitHub API客户端

9. Set Up Secrets

9. 设置密钥

Required GitHub secrets:
  • GITHUB_TOKEN
    - Automatically provided
  • GEMINI_API_KEY
    - Get from Google AI Studio
  • NPM_TOKEN
    - Only if publishing to npm
bash
undefined
所需GitHub密钥：
  • GITHUB_TOKEN
    - 系统自动提供
  • GEMINI_API_KEY
    - 从Google AI Studio获取
  • NPM_TOKEN
    - 仅当需要发布至npm时需配置
bash
undefined

Add Gemini API key to GitHub secrets

向GitHub密钥中添加Gemini API密钥

gh secret set GEMINI_API_KEY --body "your-api-key"
undefined
gh secret set GEMINI_API_KEY --body "your-api-key"
undefined

10. Verify

10. 验证

Run 
changelog-verify
to confirm everything works:
  • Commit with conventional format succeeds
  • commitlint rejects bad commits
  • Push to main triggers release workflow
  • GitHub Release created
  • LLM synthesis runs
  • Public page displays notes
运行
changelog-verify
命令确认所有功能正常工作：
  • 符合约定式提交格式的提交可成功执行
  • commitlint会拒绝不符合规范的提交
  • 推送至main分支会触发发布工作流
  • 成功创建GitHub Release
  • LLM合成功能正常运行
  • 公开页面可正常展示发布说明

Quality Gate

质量关卡

Do not consider setup complete until 
changelog-verify
passes.
只有当
changelog-verify
验证通过后，才算完成搭建工作。

Handoff

交付标准

When complete, the project should have:
  • semantic-release configured
  • commitlint enforcing conventional commits
  • Lefthook running commitlint on commit-msg
  • GitHub Actions workflow for releases
  • LLM synthesis for user-friendly notes
  • Public changelog page at 
    /changelog
  • RSS feed at 
    /changelog.xml
Developer workflow:
  1. Write code
  2. Commit with 
    feat:
    , 
    fix:
    , etc.
  3. Push/merge to main
  4. Everything else is automatic
搭建完成后，项目应具备以下内容：
  • 已配置semantic-release
  • commitlint强制实施约定式提交规范
  • Lefthook在提交消息阶段运行commitlint检查
  • GitHub Actions发布工作流
  • 用于生成用户友好说明的LLM合成功能
  • 位于
    /changelog
    的公开变更日志页面
  • 位于
    /changelog.xml
    的RSS订阅源
开发者工作流：
  1. 编写代码
  2. 使用
    feat:
    、
    fix:
    等前缀提交代码
  3. 推送/合并至main分支
  4. 后续流程全部自动完成