更新日志管理¶

遵循 Keep a Changelog 格式和最佳实践管理 CCGO 项目更新日志的指南。

概览¶

CCGO 遵循 Keep a Changelog 原则记录更改：

人类可读 - 按版本和类别组织更改
机器可解析 - 自动化工具的结构化格式
Git 集成 - 从 git 历史自动生成
语义化版本 - 与 SemVer 版本号绑定
发布说明 - 发布文档的基础

更新日志格式¶

标准结构¶

# 更新日志

本项目的所有重要更改都将记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/spec/v2.0.0.html)。

## [未发布]

### 新增
- 已添加的新功能

### 变更
- 现有功能的更改

### 弃用
- 即将在未来版本中删除的功能

### 移除
- 已删除的功能

### 修复
- 错误修复

### 安全
- 安全改进和漏洞修复

## [1.0.0] - 2024-01-15

### 新增
- 初始发布
- 跨平台 C++ 构建系统
- 支持 Android、iOS、macOS、Windows、Linux

[未发布]: https://github.com/user/project/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/project/releases/tag/v1.0.0

更改类别¶

类别	说明	示例
新增	新功能	为 Android 添加 ARM64 支持
变更	对现有功能的修改	将 CMake 最低版本更新至 3.20
弃用	标记为待删除的功能	弃用 `--legacy-build` 标志
移除	已删除的功能	移除 Python 2 支持
修复	错误修复	修复 iOS 框架中的内存泄漏
安全	安全修复	修补 XSS 漏洞

创建更新日志¶

初始设置¶

# 在项目根目录创建 CHANGELOG.md
cat > CHANGELOG.md << 'EOF'
# 更新日志

本项目的所有重要更改都将记录在此文件中。

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/spec/v2.0.0.html)。

## [未发布]

### 新增
- 初始项目设置

[未发布]: https://github.com/user/project/compare/v0.1.0...HEAD
EOF

添加更改¶

## [未发布]

### 新增
- Android ARM64-v8a 架构支持
- 基于 Docker 的 Windows 和 Linux 跨平台构建
- 从 git 标签自动注入版本

### 变更
- 将最低 CMake 版本从 3.18 更新至 3.20
- 改进缺少依赖的错误消息

### 修复
- 修复 iOS 框架符号可见性问题
- 解决 MinGW 构建中的 Windows DLL 导出问题

发布版本¶

将未发布的更改移至新版本：

## [未发布]

## [1.2.0] - 2024-01-15

### 新增
- Android ARM64-v8a 架构支持
- 基于 Docker 的跨平台构建

### 变更
- 将最低 CMake 版本从 3.18 更新至 3.20

### 修复
- 修复 iOS 框架符号可见性问题

[未发布]: https://github.com/user/project/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/project/compare/v1.1.0...v1.2.0

创建 git 标签：

ccgo tag v1.2.0 --message "Release 1.2.0"

更新版本链接：

[未发布]: https://github.com/user/project/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/user/project/compare/v1.1.0...v1.2.0
[1.1.0]: https://github.com/user/project/compare/v1.0.0...v1.1.0

自动生成更新日志¶

使用 ccgo changelog¶

# 从 git 历史生成更新日志
ccgo changelog

# 输出到文件
ccgo changelog --output CHANGELOG.md

# 在特定版本之间
ccgo changelog --from v1.0.0 --to v2.0.0

# 包含所有提交
ccgo changelog --include-all

# 按类型分组（约定式提交）
ccgo changelog --group-by-type

Git 提交解析器¶

CCGO 解析约定式提交以自动分类：

# 提交格式：<类型>(<范围>): <主题>

feat(android): add ARM64 support       → 新增
fix(ios): resolve memory leak          → 修复
docs: update installation guide        → （文档，不在更新日志中）
chore: bump version to 1.2.0          → （维护，不在更新日志中）
refactor(core): simplify error handling → 变更
test: add unit tests for calculator    → （测试，不在更新日志中）
perf(network): optimize data transfer  → 变更（性能改进）

类型映射：

提交类型	更新日志类别
`feat`	新增
`fix`	修复
`perf`	变更
`refactor`	变更
`revert`	变更
`docs`	（不包含）
`style`	（不包含）
`test`	（不包含）
`chore`	（不包含）
`build`	（不包含）
`ci`	（不包含）

破坏性更改¶

# 带破坏性更改的提交
git commit -m "feat(api)!: change function signature

BREAKING CHANGE: Calculator.add() now returns Result<int> instead of int"

在更新日志中：

## [2.0.0] - 2024-01-15

### 变更
- **破坏性更改：** Calculator.add() 现在返回 Result<int> 而不是 int

### 迁移指南
```cpp
// 之前
int result = Calculator.add(2, 3);

// 之后
auto result = Calculator.add(2, 3);
if (result.is_ok()) {
    int value = result.value();
}

## CI/CD 集成

### GitHub Actions

```yaml
name: Update Changelog
on:
  push:
    tags:
      - 'v*'

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # 完整历史用于更新日志生成

      - name: Install CCGO
        run: pip install ccgo

      - name: Generate Changelog
        run: |
          VERSION=${GITHUB_REF#refs/tags/v}
          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")

          if [ -n "$PREV_TAG" ]; then
            ccgo changelog --from $PREV_TAG --to v$VERSION --output CHANGELOG.new.md
          else
            ccgo changelog --to v$VERSION --output CHANGELOG.new.md
          fi

      - name: Update Changelog
        run: |
          # 将新更改添加到现有更新日志之前
          cat CHANGELOG.new.md CHANGELOG.md > CHANGELOG.tmp.md
          mv CHANGELOG.tmp.md CHANGELOG.md

      - name: Commit Changelog
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add CHANGELOG.md
          git commit -m "docs: update changelog for ${GITHUB_REF#refs/tags/}"
          git push

GitLab CI¶

update-changelog:
  stage: deploy
  only:
    - tags
  script:
    - pip install ccgo
    - |
      VERSION=$(echo $CI_COMMIT_TAG | sed 's/^v//')
      PREV_TAG=$(git describe --tags --abbrev=0 $CI_COMMIT_TAG^ 2>/dev/null || echo "")
      ccgo changelog --from $PREV_TAG --to $CI_COMMIT_TAG --output CHANGELOG.new.md
      cat CHANGELOG.new.md CHANGELOG.md > CHANGELOG.tmp.md
      mv CHANGELOG.tmp.md CHANGELOG.md
    - |
      git config user.name "GitLab CI"
      git config user.email "ci@gitlab.com"
      git add CHANGELOG.md
      git commit -m "docs: update changelog for $CI_COMMIT_TAG"
      git push https://oauth2:${CI_JOB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git HEAD:main

发布说明¶

生成发布说明¶

# 从更新日志生成发布说明
ccgo release-notes v1.2.0

# 输出：
# Release 1.2.0
#
# 新增：
# - Android ARM64-v8a 架构支持
# - 基于 Docker 的跨平台构建
#
# 变更：
# - 将最低 CMake 版本从 3.18 更新至 3.20
#
# 修复：
# - 修复 iOS 框架符号可见性问题

GitHub Release 集成¶

name: Create GitHub Release
on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install CCGO
        run: pip install ccgo

      - name: Generate Release Notes
        id: release_notes
        run: |
          ccgo release-notes ${GITHUB_REF#refs/tags/} --output release_notes.md
          echo "notes_file=release_notes.md" >> $GITHUB_OUTPUT

      - name: Create GitHub Release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          body_path: ${{ steps.release_notes.outputs.notes_file }}
          draft: false
          prerelease: false

最佳实践¶

1. 在每个 PR 中更新更新日志¶

## [未发布]

### 新增
- 功能 X (#123)
- 功能 Y (#124)

### 修复
- 功能 A 中的错误 (#125)

包含 PR/issue 编号以便追溯。

2. 编写以用户为中心的描述¶

# 好
- 添加对在 Apple Silicon Mac 上原生构建的支持

# 坏
- 更新 build_macos.py 以检测 arm64 架构

3. 分组相关更改¶

### Android

#### 新增
- 支持 Android 13（API 33）
- 新的 Material Design 组件

#### 修复
- Android 11 中启动时崩溃
- 后台服务中的内存泄漏

### iOS

#### 新增
- iOS 16 小部件支持
- SwiftUI 预览

#### 修复
- App Store 提交问题

4. 为破坏性更改包含迁移指南¶

## [2.0.0] - 2024-01-15

### 变更
- **破坏性更改：** 将 `ccgo build-all` 重命名为 `ccgo build --all`

### 迁移指南

更新您的构建脚本：
```bash
# 之前
ccgo build-all

# 之后
ccgo build --all

### 5. 链接到文档

```markdown
### 新增
- 基于 Docker 的跨平台构建（[文档](../features/docker-builds.zh.md)）
- 为 `ccgo build` 命令添加新的 `--docker` 标志

更新日志工具¶

changelog-cli¶

# 安装 changelog-cli
npm install -g changelog-cli

# 添加条目
changelog add "Added new feature" --type added

# 删除条目
changelog remove "Old entry"

# 发布版本
changelog release 1.2.0

git-cliff¶

# 安装 git-cliff
cargo install git-cliff

# 生成更新日志
git-cliff --output CHANGELOG.md

# 为特定范围生成
git-cliff v1.0.0..v2.0.0

conventional-changelog¶

# 安装 conventional-changelog
npm install -g conventional-changelog-cli

# 生成更新日志
conventional-changelog -p angular -i CHANGELOG.md -s

# 首次发布
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

CCGO 项目更新日志¶

示例¶

# 更新日志

## [未发布]

### 新增
- 基于 Rust 的 CLI 重写以提高性能
- 支持 Apple Watch 和 Apple TV 平台
- 所有平台统一的归档结构

### 变更
- 从 Python argparse 迁移到 Rust clap 进行 CLI 解析

## [3.0.10] - 2024-01-15

### 新增
- Git 版本控制与自动提交 SHA 注入
- 统一的归档命名约定
- 为所有平台生成符号包

### 变更
- 通过预构建镜像改进 Docker 构建性能
- 将 Android NDK 要求更新至 r21+

### 修复
- 修复 Windows MinGW 构建符号导出
- 解决 iOS 框架代码签名问题

### 安全
- 将 OpenSSL 依赖更新至 1.1.1w

## [3.0.9] - 2023-12-01

### 新增
- 基于 Docker 的跨平台构建
- 支持 OpenHarmony 平台

### 修复
- 修复 macOS 通用二进制文件生成
- 解决 Linux RPATH 问题

[未发布]: https://github.com/zhlinh/ccgo/compare/v3.0.10...HEAD
[3.0.10]: https://github.com/zhlinh/ccgo/compare/v3.0.9...v3.0.10
[3.0.9]: https://github.com/zhlinh/ccgo/releases/tag/v3.0.9

更新日志管理¶

概览¶

更新日志格式¶

标准结构¶

更改类别¶

创建更新日志¶

初始设置¶

添加更改¶

发布版本¶

自动生成更新日志¶

使用 ccgo changelog¶

Git 提交解析器¶

破坏性更改¶

GitLab CI¶

发布说明¶

生成发布说明¶

GitHub Release 集成¶

最佳实践¶

1. 在每个 PR 中更新更新日志¶

2. 编写以用户为中心的描述¶

3. 分组相关更改¶

4. 为破坏性更改包含迁移指南¶

更新日志工具¶

changelog-cli¶

git-cliff¶

conventional-changelog¶

CCGO 项目更新日志¶

示例¶

资源¶

规范¶

工具¶

CCGO 文档¶

社区¶

下一步¶