变更日志生成

原则与输入

去重：同一功能多 PR 合并为一条用户向描述。链接：issue、PR、文档锚点按需附加。多包：每包独立小节或统一根 CHANGELOG 的择一规则须在 SKILL 中写死。

# CHANGELOG.md 标准格式（Keep a Changelog）
# 可直接复制此模板到项目根目录

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

## [Unreleased]
### Added
- （开发中的新功能在此记录，发版时移到对应版本块）

## [1.5.0] - 2024-04-10
### Added
- OAuth 2.1 PKCE 支持，增强公共客户端安全性 ([#1234](https://github.com/myorg/myapp/pull/1234))
- 新增用户偏好设置 API `PATCH /users/me/preferences`

### Changed
- 商品列表 API 性能优化，P99 从 800ms 降至 120ms ([#1256](https://github.com/myorg/myapp/pull/1256))

### Fixed
- 修复并发刷新 token 时的竞态条件 ([#1198](https://github.com/myorg/myapp/issues/1198))

### Security
- 升级 jsonwebtoken 至 9.x，修复 CVE-2022-23529

## [1.4.3] - 2024-03-15
### Fixed
- 修复 Safari 下支付回调解析失败问题

[Unreleased]: https://github.com/myorg/myapp/compare/v1.5.0...HEAD
[1.5.0]: https://github.com/myorg/myapp/compare/v1.4.3...v1.5.0
[1.4.3]: https://github.com/myorg/myapp/compare/v1.4.2...v1.4.3

Keep a Changelog 小节

推荐沿用 Keep a Changelog 的英文小节标题（便于工具解析与社区一致）。每个版本块内按读者价值排序，而非按合并时间堆砌。

• Added — 新能力、新 API、用户可见的新选项。
• Changed — 行为调整但保持兼容；性能优化若对用户可感知也放此处。
• Deprecated — 仍可用但计划移除的接口；写明替代方案与移除时间表。
• Removed — 本版本已删除的公开 API 或行为。
• Fixed — 缺陷修复；内部重构若无行为变化通常不写进对外 CHANGELOG。
• Security — 安全相关修复（可与责任披露策略对齐，不一定逐条写细节）。

SemVer 与版本号

语义化版本 MAJOR.MINOR.PATCH（可选先行版本与构建元数据）应与 CHANGELOG 中「破坏性 / 新功能 / 修复」的归类一致，供 Agent 与发布工具共用同一套规则。

• MAJOR — 不兼容的 API 或行为变更；CHANGELOG 中须有 BREAKING 或 Removed 等对应说明。
• MINOR — 向后兼容的功能新增；对应 Added（及非破坏的 Changed）。
• PATCH — 向后兼容的问题修复；主要对应 Fixed / Security（在无破坏性时）。

若团队使用日历版本（CalVer）或固定营销版本号，须在 SKILL 中单独说明，避免 Agent 仍按 SemVer 去「推算」下一版。

起草流程

从原始提交到可发布文本，建议固定顺序，减少漏项与分类错误。

  [ 锁定范围：tag / 日期 / commit 区间 ]
                    │
                    ▼
              [ 聚合 PR / issue：去重、补链接 ]
                    │
                    ▼
         [ 归类到 KaC 小节 + 标 BREAKING? ]
                    │
                    ▼
              [ 对照 SemVer 规则草案版本号 ]
                    │
                    ▼
         [ 人工润色：语气、迁移、安全措辞 ]
                    │
                    ▼
              [ 与自动化输出 diff：去重段落 ]

自动化与边界

与 release-please、semantic-release、changesets 等工具并存时，写明「机器生成段」与「人工润色段」的边界：例如标题与日期由 CI 写，条目由 PR 模板收集，Agent 只负责把草稿改成用户向叙述。

# semantic-release 配置示例（.releaserc.json）
{
  "branches": ["main", {"name": "release/+([0-9])+(.{+([0-9]),x}).x", "range": "${name.replace(/release\\//,'')}","channel": "maintenance"}],
  "plugins": [
    ["@semantic-release/commit-analyzer", {
      "preset": "conventionalcommits",
      "releaseRules": [
        {"type": "feat",  "release": "minor"},
        {"type": "fix",   "release": "patch"},
        {"type": "perf",  "release": "patch"},
        {"type": "revert","release": "patch"},
        {"breaking": true,"release": "major"}
      ]
    }],
    ["@semantic-release/release-notes-generator", {
      "preset": "conventionalcommits",
      "presetConfig": {
        "types": [
          {"type": "feat",     "section": "Features"},
          {"type": "fix",      "section": "Bug Fixes"},
          {"type": "perf",     "section": "Performance"},
          {"type": "security", "section": "Security", "hidden": false}
        ]
      }
    }],
    ["@semantic-release/changelog", {"changelogFile": "CHANGELOG.md"}],
    ["@semantic-release/npm"],
    ["@semantic-release/github", {"assets": [{"path": "dist/*.tar.gz"}]}],
    ["@semantic-release/git", {
      "assets": ["CHANGELOG.md", "package.json"],
      "message": "chore(release): ${nextRelease.version} [skip ci]"
    }]
  ]
}

# GitHub Actions：自动创建 Release（release-please 方案）
# .github/workflows/release-please.yml
name: Release Please
on:
  push:
    branches: [main]

permissions:
  contents: write
  pull-requests: write

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v4
        id: release
        with:
          release-type: node
          token: ${{ secrets.GITHUB_TOKEN }}

      # 仅在 release PR 被合并后（实际发布）才执行部署
      - uses: actions/checkout@v4
        if: ${{ steps.release.outputs.release_created }}

      - name: Deploy to production
        if: ${{ steps.release.outputs.release_created }}
        run: |
          echo "Deploying version ${{ steps.release.outputs.tag_name }}"
          ./scripts/deploy.sh "${{ steps.release.outputs.tag_name }}"

避免同一发行在 CHANGELOG 中出现两段重复描述；若工具会追加 commit 列表，SKILL 可规定「仅保留摘要句 + 链接，不重复列举 hash」。

小节预览与版本推算

下方可展开各小节备忘（仅本页展示）；版本推算按纯 MAJOR.MINOR.PATCH 规则，不含先行版语义。演算在浏览器本地完成，不上传。