changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/changelog

Automated changelogs, semantic versioning, and user-friendly release notes. Audit, fix, verify—every time.

自动化变更日志、语义化版本控制，以及用户友好的发布说明。每次执行都包含审计、修复、验证全流程。

What This Does

功能说明

Examines your release infrastructure, identifies every gap, implements fixes, and verifies the full pipeline works. No partial modes. Every run does the full cycle.

检查您的发布基础设施，识别所有漏洞，实施修复方案，并验证完整流水线的运行情况。不支持部分模式，每次运行都会执行全周期流程。

Process

实施流程

1. Audit

1. 审计

Check what exists and what's broken:

bash

undefined

检查现有配置及存在的问题：

bash

undefined

Configuration

[ -f ".releaserc.js" ] || [ -f ".releaserc.json" ] && echo "✓ semantic-release" || echo "✗ semantic-release" [ -f "commitlint.config.js" ] || [ -f "commitlint.config.cjs" ] && echo "✓ commitlint" || echo "✗ commitlint" grep -q "commit-msg" lefthook.yml 2>/dev/null && echo "✓ commit-msg hook" || echo "✗ commit-msg hook"

GitHub Actions

[ -f ".github/workflows/release.yml" ] && echo "✓ release workflow" || echo "✗ release workflow" grep -q "semantic-release" .github/workflows/release.yml 2>/dev/null && echo "✓ runs semantic-release" || echo "✗ doesn't run semantic-release" grep -q "GEMINI_API_KEY" .github/workflows/release.yml 2>/dev/null && echo "✓ LLM synthesis configured" || echo "✗ LLM synthesis missing"

Public page

ls app/changelog/page.tsx src/app/changelog/page.tsx 2>/dev/null && echo "✓ changelog page" || echo "✗ changelog page"

Health

gh release list --limit 3 2>/dev/null || echo "✗ no releases"


**Commit history check:**
```bash
git log --oneline -10 | while read line; do
  echo "$line" | grep -qE "^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: " || echo "NON-CONVENTIONAL: $line"
done

gh release list --limit 3 2>/dev/null || echo "✗ no releases"


**提交历史检查：**
```bash
git log --oneline -10 | while read line; do
  echo "$line" | grep -qE "^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: " || echo "NON-CONVENTIONAL: $line"
done

2. Plan

2. 规划

From audit findings, build remediation plan. Every project needs:

Must have:

semantic-release configured with changelog, git, github plugins
commitlint enforcing conventional commits
Lefthook commit-msg hook running commitlint
GitHub Actions workflow running semantic-release on push to main

Should have:

LLM synthesis transforming technical changelog to user-friendly notes
Public
```
/changelog
```
page fetching from GitHub Releases API
RSS feed at
```
/changelog.xml
```
or
```
/changelog/rss
```

基于审计结果，制定修复计划。每个项目都需要：

必备组件：

配置带有changelog、git、github插件的semantic-release
用于规范提交信息的commitlint
运行commitlint的Lefthook commit-msg钩子
推送至main分支时自动运行semantic-release的GitHub Actions工作流

推荐组件：

将技术型变更日志转换为用户友好说明的LLM合成功能
从GitHub Releases API拉取数据的公开
```
/changelog
```
页面
位于
```
/changelog.xml
```
或
```
/changelog/rss
```
的RSS订阅源

3. Execute

3. 执行

Fix everything. Don't stop at a report.

Installing semantic-release:

bash

pnpm add -D semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/github

Create

.releaserc.js

javascript

module.exports = {
  branches: ['main'],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    ['@semantic-release/changelog', { changelogFile: 'CHANGELOG.md' }],
    ['@semantic-release/git', { assets: ['CHANGELOG.md', 'package.json'] }],
    '@semantic-release/github',
  ],
};

Installing commitlint:

bash

pnpm add -D @commitlint/cli @commitlint/config-conventional

Create

commitlint.config.js

javascript

module.exports = { extends: ['@commitlint/config-conventional'] };

Add to

lefthook.yml

yaml

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

Creating release workflow: Create

.github/workflows/release.yml

per

changelog-setup

reference.

Adding LLM synthesis:

REQUIRED: Before implementing, read
llm-infrastructure/references/model-research-required.md
Do NOT use model names from this document or your training data. Run the OpenRouter fetch script and web search to determine current best model for this task.

Steps:

Research current models (MANDATORY):

bash

# Query OpenRouter for current fast/cheap models
python3 ~/.claude/skills/llm-infrastructure/scripts/fetch-openrouter-models.py \
  --task fast --filter "google|anthropic|openai" --top 10

# Web search: "best LLM for text summarization 2026"
# Web search: "Gemini API current models 2026"

Create
```
scripts/synthesize-release-notes.mjs
```
that:
- Fetches latest release from GitHub API
- Uses OpenRouter API (not direct provider APIs) for flexibility
- Model name comes from environment variable, NOT hardcoded
- Gets user-friendly summary back
- Updates release body via GitHub API
Configure secrets in GitHub:
- ```
OPENROUTER_API_KEY
```
  (preferred) or provider-specific key
- Model name as environment variable (e.g.,
```
LLM_MODEL_SYNTHESIS
```
  )

Creating public changelog page: Per

changelog-page

, create:

```
app/changelog/page.tsx
```
- Fetches from GitHub Releases API
Groups releases by minor version
No auth required (public page)
RSS feed support

Making changelog discoverable (CRITICAL): A changelog page that users can't find is useless. Ensure:

Footer link: Add "changelog" link to global footer (visible on landing page)
Settings link: Add "View changelog" link in app settings/about section
Version display: Show current app version in settings (use
```
NEXT_PUBLIC_APP_VERSION
```
env var)
RSS link: Mention RSS feed on the changelog page itself

Example footer links:

tsx

<Link href="/changelog">changelog</Link>
<Link href="/support">support</Link>
<Link href="/privacy">privacy</Link>

Example settings "About" section:

tsx

<div className="flex items-center justify-between">
  <span>Version</span>
  <span className="font-mono">{process.env.NEXT_PUBLIC_APP_VERSION || '0.1.0'}</span>
</div>
<Link href="/changelog">View changelog →</Link>

Delegate implementation to Codex where appropriate.

修复所有问题，不只是生成报告。

安装semantic-release：

bash

pnpm add -D semantic-release @semantic-release/changelog @semantic-release/git @semantic-release/github

创建

.releaserc.js

：

javascript

module.exports = {
  branches: ['main'],
  plugins: [
    '@semantic-release/commit-analyzer',
    '@semantic-release/release-notes-generator',
    ['@semantic-release/changelog', { changelogFile: 'CHANGELOG.md' }],
    ['@semantic-release/git', { assets: ['CHANGELOG.md', 'package.json'] }],
    '@semantic-release/github',
  ],
};

安装commitlint：

bash

pnpm add -D @commitlint/cli @commitlint/config-conventional

创建

commitlint.config.js

：

javascript

module.exports = { extends: ['@commitlint/config-conventional'] };

添加至

lefthook.yml

：

yaml

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

创建发布工作流： 参考

changelog-setup

创建

.github/workflows/release.yml

。

添加LLM合成功能：

注意： 实施前请阅读
llm-infrastructure/references/model-research-required.md
请勿使用本文档或训练数据中的模型名称。运行OpenRouter获取脚本并通过网络搜索确定当前适用于此任务的最佳模型。

步骤：

调研当前模型（必填）：

bash

# Query OpenRouter for current fast/cheap models
python3 ~/.claude/skills/llm-infrastructure/scripts/fetch-openrouter-models.py \
  --task fast --filter "google|anthropic|openai" --top 10

# Web search: "best LLM for text summarization 2026"
# Web search: "Gemini API current models 2026"

创建
```
scripts/synthesize-release-notes.mjs
```
，实现以下功能：
- 从GitHub API获取最新发布信息
- 使用OpenRouter API（优先选择，而非直接使用供应商API）以保证灵活性
- 模型名称来自环境变量，而非硬编码
- 生成用户友好的摘要
- 通过GitHub API更新发布内容
在GitHub中配置密钥：
- ```
OPENROUTER_API_KEY
```
  （优先）或特定供应商的密钥
- 作为环境变量的模型名称（例如
```
LLM_MODEL_SYNTHESIS
```
  ）

创建公开变更日志页面： 参考

changelog-page

创建：

```
app/changelog/page.tsx
```
- 从GitHub Releases API拉取数据
按次要版本分组展示发布记录
无需认证（公开页面）
支持RSS订阅源

确保变更日志可被发现（至关重要）： 用户找不到的变更日志毫无用处。请确保：

页脚链接：在全局页脚添加“changelog”链接（在首页可见）
设置页面链接：在应用设置/关于部分添加“查看变更日志”链接
版本显示：在设置中显示当前应用版本（使用
```
NEXT_PUBLIC_APP_VERSION
```
环境变量）
RSS链接：在变更日志页面本身提及RSS订阅源

页脚链接示例：

tsx

<Link href="/changelog">changelog</Link>
<Link href="/support">support</Link>
<Link href="/privacy">privacy</Link>

设置页面“关于”部分示例：

tsx

<div className="flex items-center justify-between">
  <span>Version</span>
  <span className="font-mono">{process.env.NEXT_PUBLIC_APP_VERSION || '0.1.0'}</span>
</div>
<Link href="/changelog">View changelog →</Link>

适当情况下可将实现工作委托给Codex。

4. Verify

4. 验证

Prove it works. Not "config exists"—actually works.

Commitlint test:

bash

echo "bad message" | pnpm commitlint

证明流程可正常运行，不只是“配置存在”，而是实际可用。

Commitlint测试：

bash

echo "bad message" | pnpm commitlint

Should fail

echo "feat: valid message" | pnpm commitlint

Should pass


**Commit hook test:**
```bash


**提交钩子测试：**
```bash

Try to commit with bad message (should be rejected)

git commit --allow-empty -m "bad message"

Should fail due to commitlint hook


**Release workflow test:**
If you can trigger a release:
1. Merge a PR with `feat:` or `fix:` commit
2. Watch GitHub Actions run
3. Verify:
   - Version bumped in package.json
   - CHANGELOG.md updated
   - GitHub Release created
   - Release notes populated (LLM synthesis ran)

**Public page test:**
- Navigate to `/changelog`
- Verify releases displayed
- Verify grouped by minor version
- Check RSS feed works

If any verification fails, go back and fix it.


**发布工作流测试：**
如果可以触发发布：
1. 合并带有`feat:`或`fix:`提交信息的PR
2. 观察GitHub Actions运行情况
3. 验证以下内容：
   - package.json中的版本号已更新
   - CHANGELOG.md已更新
   - 已创建GitHub Release
   - 已填充发布说明（LLM合成功能已运行）

**公开页面测试：**
- 访问`/changelog`
- 验证发布记录已展示
- 验证已按次要版本分组
- 检查RSS订阅源是否可用

如果任何验证步骤失败，请返回并修复问题。

The Release Flow

发布流程

Commit with conventional format (enforced by Lefthook)
       ↓
Push/merge to main
       ↓
GitHub Actions runs semantic-release
       ↓
Version bumped, CHANGELOG.md updated, GitHub Release created
       ↓
Post-release action triggers LLM synthesis
       ↓
LLM (via OpenRouter) transforms changelog → user notes
       ↓
Enhanced notes stored in GitHub Release
       ↓
Public /changelog page displays latest

Commit with conventional format (enforced by Lefthook)
       ↓
Push/merge to main
       ↓
GitHub Actions runs semantic-release
       ↓
Version bumped, CHANGELOG.md updated, GitHub Release created
       ↓
Post-release action triggers LLM synthesis
       ↓
LLM (via OpenRouter) transforms changelog → user notes
       ↓
Enhanced notes stored in GitHub Release
       ↓
Public /changelog page displays latest

Key Principles

核心原则

Every merge is a release. Web apps deploy on merge. Embrace frequent releases.

Every change gets notes. Even

chore:

commits become "Behind-the-scenes improvements."

Group for readability. Public page groups patches under their minor version.

Auto-publish. No human gate on LLM synthesis. Trust the pipeline.

每次合并都是一次发布。Web应用在合并时部署，拥抱频繁发布。

每个变更都有说明。即使是

chore:

类型的提交也会转换为“后台优化”。

分组提升可读性。公开页面将补丁版本归到对应的次要版本下展示。

自动发布。LLM合成无需人工审核，信任流水线的能力。

Default Stack

默认技术栈

Assumes Next.js + TypeScript + GitHub. Adapts gracefully to other stacks.

假设使用Next.js + TypeScript + GitHub，可灵活适配其他技术栈。

What You Get

最终成果

When complete:

semantic-release configured and working
Conventional commits enforced (can't commit without format)
GitHub Actions workflow for releases
LLM synthesis for user-friendly notes (model via env var)
Public
```
/changelog
```
page with RSS feed
Discoverable links from footer and settings
Version displayed in app settings
Verified end-to-end

User can:

Merge a PR with conventional commit
See automatic version bump
See GitHub Release created
See user-friendly notes synthesized
Find changelog from footer or settings (not hidden)
See what version they're running
Subscribe to RSS feed for updates

完成后，您将获得：

已配置并可正常运行的semantic-release
强制规范的提交信息（不符合格式无法提交）
用于发布的GitHub Actions工作流
基于环境变量指定模型的LLM合成用户友好说明功能
带有RSS订阅源的公开
```
/changelog
```
页面
可从页脚和设置页面访问的链接
在应用设置中显示的版本号
端到端验证通过的完整流程

用户可：

合并带有规范提交信息的PR
查看自动更新的版本号
查看已创建的GitHub Release
查看合成后的用户友好说明
从页脚或设置页面找到变更日志（不会隐藏）
查看当前运行的应用版本
订阅RSS源获取更新