Changelog Management¶

Guide to managing changelogs in CCGO projects following Keep a Changelog format and best practices.

Overview¶

CCGO follows Keep a Changelog principles for documenting changes:

Human-Readable - Changes organized by version and category
Machine-Parseable - Structured format for automated tools
Git Integration - Automated generation from git history
Semantic Versioning - Tied to SemVer version numbers
Release Notes - Foundation for release documentation

Changelog Format¶

Standard Structure¶

# 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- New features that have been added

### Changed
- Changes in existing functionality

### Deprecated
- Features that will be removed in upcoming releases

### Removed
- Features that have been removed

### Fixed
- Bug fixes

### Security
- Security improvements and vulnerability fixes

## [1.0.0] - 2024-01-15

### Added
- Initial release
- Cross-platform C++ build system
- Support for Android, iOS, macOS, Windows, Linux

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

Change Categories¶

Category	Description	Example
Added	New features	Added ARM64 support for Android
Changed	Modifications to existing features	Updated CMake minimum version to 3.20
Deprecated	Features marked for removal	Deprecated `--legacy-build` flag
Removed	Deleted features	Removed Python 2 support
Fixed	Bug fixes	Fixed memory leak in iOS framework
Security	Security fixes	Patched XSS vulnerability

Creating a Changelog¶

Initial Setup¶

# Create CHANGELOG.md in project root
cat > CHANGELOG.md << 'EOF'
# 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.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Initial project setup

[Unreleased]: https://github.com/user/project/compare/v0.1.0...HEAD
EOF

Adding Changes¶

## [Unreleased]

### Added
- Android ARM64-v8a architecture support
- Docker-based cross-platform builds for Windows and Linux
- Automatic version injection from git tags

### Changed
- Updated minimum CMake version from 3.18 to 3.20
- Improved error messages for missing dependencies

### Fixed
- Fixed iOS framework symbol visibility issues
- Resolved Windows DLL export problems in MinGW builds

Releasing a Version¶

Move unreleased changes to new version:

## [Unreleased]

## [1.2.0] - 2024-01-15

### Added
- Android ARM64-v8a architecture support
- Docker-based cross-platform builds

### Changed
- Updated minimum CMake version from 3.18 to 3.20

### Fixed
- Fixed iOS framework symbol visibility issues

[Unreleased]: 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

Create git tag:

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

Update version links:

[Unreleased]: 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

Automated Changelog Generation¶

Using ccgo changelog¶

# Generate changelog from git history
ccgo changelog

# Output to file
ccgo changelog --output CHANGELOG.md

# Between specific versions
ccgo changelog --from v1.0.0 --to v2.0.0

# Include all commits
ccgo changelog --include-all

# Group by type (conventional commits)
ccgo changelog --group-by-type

Git Commit Parser¶

CCGO parses Conventional Commits for automatic categorization:

# Commit format: <type>(<scope>): <subject>

feat(android): add ARM64 support       → Added
fix(ios): resolve memory leak          → Fixed
docs: update installation guide        → (Documentation, not in changelog)
chore: bump version to 1.2.0          → (Maintenance, not in changelog)
refactor(core): simplify error handling → Changed
test: add unit tests for calculator    → (Testing, not in changelog)
perf(network): optimize data transfer  → Changed (performance improvement)

Type Mapping:

Commit Type	Changelog Category
`feat`	Added
`fix`	Fixed
`perf`	Changed
`refactor`	Changed
`revert`	Changed
`docs`	(Not included)
`style`	(Not included)
`test`	(Not included)
`chore`	(Not included)
`build`	(Not included)
`ci`	(Not included)

Breaking Changes¶

# Commit with breaking change
git commit -m "feat(api)!: change function signature

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

In Changelog:

## [2.0.0] - 2024-01-15

### Changed
- **BREAKING:** Calculator.add() now returns Result<int> instead of int

### Migration Guide
```cpp
// Before
int result = Calculator.add(2, 3);

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

## CI/CD Integration

### 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  # Full history for changelog generation

      - 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: |
          # Prepend new changes to existing changelog
          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

Release Notes¶

Generating Release Notes¶

# Generate release notes from changelog
ccgo release-notes v1.2.0

# Output:
# Release 1.2.0
#
# Added:
# - Android ARM64-v8a architecture support
# - Docker-based cross-platform builds
#
# Changed:
# - Updated minimum CMake version from 3.18 to 3.20
#
# Fixed:
# - Fixed iOS framework symbol visibility issues

GitHub Release Integration¶

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

Best Practices¶

1. Update Changelog with Every PR¶

## [Unreleased]

### Added
- Feature X (#123)
- Feature Y (#124)

### Fixed
- Bug in feature A (#125)

Include PR/issue numbers for traceability.

2. Write User-Focused Descriptions¶

# Good
- Added support for building on Apple Silicon Macs natively

# Bad
- Updated build_macos.py to detect arm64 architecture

### Android

#### Added
- Support for Android 13 (API 33)
- New material design components

#### Fixed
- Crash on startup in Android 11
- Memory leak in background service

### iOS

#### Added
- iOS 16 widget support
- SwiftUI previews

#### Fixed
- App Store submission issues

4. Include Migration Guides for Breaking Changes¶

## [2.0.0] - 2024-01-15

### Changed
- **BREAKING:** Renamed `ccgo build-all` to `ccgo build --all`

### Migration Guide

Update your build scripts:
```bash
# Before
ccgo build-all

# After
ccgo build --all

### 5. Link to Documentation

```markdown
### Added
- Docker-based cross-platform builds ([documentation](../features/docker-builds.md))
- New `--docker` flag for `ccgo build` command

Changelog Tools¶

changelog-cli¶

# Install changelog-cli
npm install -g changelog-cli

# Add entry
changelog add "Added new feature" --type added

# Remove entry
changelog remove "Old entry"

# Release version
changelog release 1.2.0

git-cliff¶

# Install git-cliff
cargo install git-cliff

# Generate changelog
git-cliff --output CHANGELOG.md

# Generate for specific range
git-cliff v1.0.0..v2.0.0

conventional-changelog¶

# Install conventional-changelog
npm install -g conventional-changelog-cli

# Generate changelog
conventional-changelog -p angular -i CHANGELOG.md -s

# First release
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

CCGO Project Changelog¶

Example¶

# Changelog

## [Unreleased]

### Added
- Rust-based CLI rewrite for improved performance
- Support for Apple Watch and Apple TV platforms
- Unified archive structure across all platforms

### Changed
- Migrated from Python argparse to Rust clap for CLI parsing

## [3.0.10] - 2024-01-15

### Added
- Git versioning with automatic commit SHA injection
- Unified archive naming convention
- Symbols package generation for all platforms

### Changed
- Improved Docker build performance with prebuilt images
- Updated Android NDK requirement to r21+

### Fixed
- Fixed Windows MinGW build symbol exports
- Resolved iOS framework code signing issues

### Security
- Updated OpenSSL dependency to 1.1.1w

## [3.0.9] - 2023-12-01

### Added
- Docker-based cross-platform builds
- Support for OpenHarmony platform

### Fixed
- Fixed macOS universal binary generation
- Resolved Linux RPATH issues

[Unreleased]: 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

Changelog Management¶

Overview¶

Changelog Format¶

Standard Structure¶

Change Categories¶

Creating a Changelog¶

Initial Setup¶

Adding Changes¶

Releasing a Version¶

Automated Changelog Generation¶

Using ccgo changelog¶

Git Commit Parser¶

Breaking Changes¶

GitLab CI¶

Release Notes¶

Generating Release Notes¶

GitHub Release Integration¶

Best Practices¶

1. Update Changelog with Every PR¶

2. Write User-Focused Descriptions¶

4. Include Migration Guides for Breaking Changes¶

Changelog Tools¶

changelog-cli¶

git-cliff¶

conventional-changelog¶

CCGO Project Changelog¶

Example¶

Resources¶

Specifications¶

Tools¶

CCGO Documentation¶

Community¶

Next Steps¶

Changelog Management¶

Overview¶

Changelog Format¶

Standard Structure¶

Change Categories¶

Creating a Changelog¶

Initial Setup¶

Adding Changes¶

Releasing a Version¶

Automated Changelog Generation¶

Using ccgo changelog¶

Git Commit Parser¶

Breaking Changes¶

GitLab CI¶

Release Notes¶

Generating Release Notes¶

GitHub Release Integration¶

Best Practices¶

1. Update Changelog with Every PR¶

2. Write User-Focused Descriptions¶

3. Group Related Changes¶

4. Include Migration Guides for Breaking Changes¶

Changelog Tools¶

changelog-cli¶

git-cliff¶

conventional-changelog¶

CCGO Project Changelog¶

Example¶

Resources¶

Specifications¶

Tools¶

CCGO Documentation¶

Community¶

Next Steps¶