changelog-setup（变更日志设置）

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)

Run changelog-assess to confirm this is actually greenfield. If partial infrastructure exists, consider audit/reconcile instead.

2. Install Dependencies

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

3. Configure semantic-release

Create .releaserc.js:

// 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',
  ],
};

4. Configure commitlint

Create commitlint.config.js:

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

Update lefthook.yml (create if doesn't exist):

commit-msg:
  commands:
    commitlint:
      run: pnpm commitlint --edit {1}

Run pnpm lefthook install to activate.

6. Create GitHub Actions Workflow

Create .github/workflows/release.yml:

# See references/github-actions-release.md for full workflow
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

7. Configure LLM Synthesis

Create .release-notes-config.yml:

# 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)

8. Scaffold Public Changelog Page

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

9. Set Up Secrets

Required GitHub secrets:

• GITHUB_TOKEN - Automatically provided
• GEMINI_API_KEY - Get from Google AI Studio
• NPM_TOKEN - Only if publishing to npm

# Add Gemini API key to GitHub secrets
gh secret set GEMINI_API_KEY --body "your-api-key"

10. Verify

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

Quality Gate

Do not consider setup complete until changelog-verify passes.

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