Back to Details

ogt-docs-changelog

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OGT Docs - Changelog

OGT 文档 - 变更日志

Manage project changelog following Keep a Changelog format.
遵循Keep a Changelog格式管理项目变更日志。

Overview

概述

The changelog documents all notable changes to the project. It follows Keep a Changelog format and is maintained in 
CHANGELOG.md
at the project root.
mermaid
flowchart LR
    subgraph sources ["Change Sources"]
        COMMITS["Git Commits"]
        TASKS["Done Tasks"]
        PRS["Pull Requests"]
    end

    subgraph changelog ["CHANGELOG.md"]
        UNREL["[Unreleased]"]
        V2["[2.0.0]"]
        V1["[1.1.0]"]
        V0["[1.0.0]"]
    end

    COMMITS --> UNREL
    TASKS --> UNREL
    PRS --> UNREL

    UNREL -->|release| V2
变更日志记录了项目中所有值得关注的变更。它遵循Keep a Changelog格式，保存在项目根目录的
CHANGELOG.md
文件中。
mermaid
flowchart LR
    subgraph sources ["Change Sources"]
        COMMITS["Git Commits"]
        TASKS["Done Tasks"]
        PRS["Pull Requests"]
    end

    subgraph changelog ["CHANGELOG.md"]
        UNREL["[Unreleased]"]
        V2["[2.0.0]"]
        V1["[1.1.0]"]
        V0["[1.0.0]"]
    end

    COMMITS --> UNREL
    TASKS --> UNREL
    PRS --> UNREL

    UNREL -->|release| V2

When to Use

适用场景

  • Adding entries for completed work
  • Preparing a release
  • Generating changelog from commits
  • Reviewing change history
  • Communicating updates to users
  • 为已完成的工作添加条目
  • 准备版本发布
  • 从提交记录生成变更日志
  • 查阅变更历史
  • 向用户传达更新内容

Changelog Structure

变更日志结构

markdown
undefined
markdown
undefined

Changelog

Changelog

All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[Unreleased]

Added

Added

  • New feature description
  • New feature description

Changed

Changed

  • Change description
  • Change description

Deprecated

Deprecated

  • Deprecation notice
  • Deprecation notice

Removed

Removed

  • Removal description
  • Removal description

Fixed

Fixed

  • Bug fix description
  • Bug fix description

Security

Security

  • Security fix description
  • Security fix description

[1.0.0] - 2026-02-01

[1.0.0] - 2026-02-01

Added

Added

  • Initial release features

---
  • Initial release features

---

Change Categories

变更分类

CategoryDescriptionExamples
AddedNew featuresNew API endpoint, new component
ChangedChanges to existing functionalityUpdated behavior, redesign
DeprecatedFeatures to be removedOld API marked for removal
RemovedRemoved featuresDeleted endpoint, removed option
FixedBug fixesCrash fix, data correction
SecuritySecurity fixesVulnerability patch
分类描述示例
Added新增功能新API端点、新组件
Changed现有功能变更行为更新、界面重设计
Deprecated标记为待移除的功能旧API标记为待移除
Removed已移除的功能删除的端点、移除的选项
Fixed缺陷修复崩溃修复、数据修正
Security安全修复漏洞补丁

Category Order

分类顺序

Always list in this order:
  1. Added
  2. Changed
  3. Deprecated
  4. Removed
  5. Fixed
  6. Security
请始终按照以下顺序排列：
  1. Added
  2. Changed
  3. Deprecated
  4. Removed
  5. Fixed
  6. Security

Entry Format

条目格式

Basic Entry

基础条目

markdown
undefined
markdown
undefined

Added

Added

  • Steam OAuth authentication support (#123)
undefined
  • Steam OAuth authentication support (#123)
undefined

Entry with Details

带详情的条目

markdown
undefined
markdown
undefined

Added

Added

  • Steam OAuth authentication support (#123)
    • Login via Steam OpenID
    • Profile sync with Steam display name
    • Automatic account linking for existing users
undefined
  • Steam OAuth authentication support (#123)
    • Login via Steam OpenID
    • Profile sync with Steam display name
    • Automatic account linking for existing users
undefined

Entry with Migration Note

带迁移说明的条目

markdown
undefined
markdown
undefined

Changed

Changed

  • API authentication header format (#456)
    • Now requires "Bearer " prefix
    • See migration guide
undefined
  • API authentication header format (#456)
    • Now requires "Bearer " prefix
    • See migration guide
undefined

Breaking Change Entry

破坏性变更条目

markdown
undefined
markdown
undefined

Changed

Changed

  • BREAKING: Renamed 
    /api/monsters
    to 
    /api/creatures
    (#789)
    • All monster endpoints now use creature terminology
    • See migration guide

---
  • BREAKING: Renamed 
    /api/monsters
    to 
    /api/creatures
    (#789)
    • All monster endpoints now use creature terminology
    • See migration guide

---

Adding Entries

添加条目

Manual Addition

手动添加

bash
undefined
bash
undefined

Open changelog

Open changelog

vim CHANGELOG.md
vim CHANGELOG.md

Add entry under [Unreleased] in appropriate category

Add entry under [Unreleased] in appropriate category

undefined
undefined

From Completed Task

从已完成任务添加

When a task moves to 
done/
:
bash
undefined
当任务移入
done/
目录时：
bash
undefined

1. Read the task summary

1. 读取任务摘要

cat docs/todo/done/{task}/task.md | head -20
cat docs/todo/done/{task}/task.md | head -20

2. Determine category (Added/Changed/Fixed/etc.)

2. 确定分类（Added/Changed/Fixed等）

3. Add to CHANGELOG.md under [Unreleased]

3. 添加到CHANGELOG.md的[Unreleased]部分下

undefined
undefined

From Conventional Commits

从约定式提交添加

Parse conventional commits to generate entries:
bash
undefined
解析约定式提交记录以生成条目：
bash
undefined

Get commits since last tag

获取自上次标签以来的提交记录

git log $(git describe --tags --abbrev=0)..HEAD --oneline
git log $(git describe --tags --abbrev=0)..HEAD --oneline

Parse by type

按类型解析

feat: -> Added

feat: -> Added

fix: -> Fixed

fix: -> Fixed

refactor: -> Changed

refactor: -> Changed

docs: -> (usually skip or Added)

docs: -> 通常跳过或归类到Added


---

---

Release Workflow

版本发布流程

Step 1: Review Unreleased

步骤1：审阅未发布变更

bash
undefined
bash
undefined

View current unreleased changes

查看当前未发布的变更

sed -n '/## [Unreleased]/,/## [/p' CHANGELOG.md | head -n -1
undefined
sed -n '/## [Unreleased]/,/## [/p' CHANGELOG.md | head -n -1
undefined

Step 2: Determine Version

步骤2：确定版本号

Based on changes:
  • MAJOR: Breaking changes present → 
    X.0.0
  • MINOR: New features, no breaking → 
    x.X.0
  • PATCH: Only fixes → 
    x.x.X
根据变更类型确定：
  • MAJOR：存在破坏性变更 → 
    X.0.0
  • MINOR：新增功能，无破坏性变更 → 
    x.X.0
  • PATCH：仅包含缺陷修复 → 
    x.x.X

Step 3: Create Release Section

步骤3：创建版本发布章节

markdown
undefined
markdown
undefined

[Unreleased]

[Unreleased]

[2.1.0] - 2026-02-06

[2.1.0] - 2026-02-06

Added

Added

  • Steam OAuth authentication support (#123)
  • Global fuzzy search (#124)
  • Steam OAuth authentication support (#123)
  • Global fuzzy search (#124)

Fixed

Fixed

  • Null response handling in legacy API (#125)
undefined
  • Null response handling in legacy API (#125)
undefined

Step 4: Update Links

步骤4：更新链接

markdown
[Unreleased]: https://github.com/org/repo/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/org/repo/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/org/repo/releases/tag/v2.0.0
markdown
[Unreleased]: https://github.com/org/repo/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/org/repo/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/org/repo/releases/tag/v2.0.0

Step 5: Commit and Tag

步骤5：提交并打标签

bash
undefined
bash
undefined

Commit changelog update

提交变更日志更新

git add CHANGELOG.md git commit -m "chore(release): v2.1.0"
git add CHANGELOG.md git commit -m "chore(release): v2.1.0"

Create tag

创建标签

git tag -a v2.1.0 -m "Release v2.1.0"
git tag -a v2.1.0 -m "Release v2.1.0"

Push

推送

git push origin main --tags

---
git push origin main --tags

---

Automated Generation

自动生成

From Conventional Commits

从约定式提交生成

bash
#!/bin/bash
bash
#!/bin/bash

generate-changelog.sh

generate-changelog.sh

LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then COMMITS=$(git log --oneline) else COMMITS=$(git log ${LAST_TAG}..HEAD --oneline) fi
echo "## [Unreleased]" echo ""
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
if [ -z "$LAST_TAG" ]; then COMMITS=$(git log --oneline) else COMMITS=$(git log ${LAST_TAG}..HEAD --oneline) fi
echo "## [Unreleased]" echo ""

Added (feat commits)

Added (feat commits)

ADDED=$(echo "$COMMITS" | grep "^[a-f0-9]* feat" | sed 's/^[a-f0-9]* feat[^:]*: /- /') if [ -n "$ADDED" ]; then echo "### Added" echo "$ADDED" echo "" fi
ADDED=$(echo "$COMMITS" | grep "^[a-f0-9]* feat" | sed 's/^[a-f0-9]* feat[^:]*: /- /') if [ -n "$ADDED" ]; then echo "### Added" echo "$ADDED" echo "" fi

Fixed (fix commits)

Fixed (fix commits)

FIXED=$(echo "$COMMITS" | grep "^[a-f0-9]* fix" | sed 's/^[a-f0-9]* fix[^:]*: /- /') if [ -n "$FIXED" ]; then echo "### Fixed" echo "$FIXED" echo "" fi
FIXED=$(echo "$COMMITS" | grep "^[a-f0-9]* fix" | sed 's/^[a-f0-9]* fix[^:]*: /- /') if [ -n "$FIXED" ]; then echo "### Fixed" echo "$FIXED" echo "" fi

Changed (refactor commits)

Changed (refactor commits)

CHANGED=$(echo "$COMMITS" | grep "^[a-f0-9]* refactor" | sed 's/^[a-f0-9]* refactor[^:]*: /- /') if [ -n "$CHANGED" ]; then echo "### Changed" echo "$CHANGED" echo "" fi
undefined
CHANGED=$(echo "$COMMITS" | grep "^[a-f0-9]* refactor" | sed 's/^[a-f0-9]* refactor[^:]*: /- /') if [ -n "$CHANGED" ]; then echo "### Changed" echo "$CHANGED" echo "" fi
undefined

From Done Tasks

从已完成任务生成

bash
#!/bin/bash
bash
#!/bin/bash

changelog-from-tasks.sh

changelog-from-tasks.sh

echo "## Changes from completed tasks" echo ""
for task_dir in docs/todo/done/*/; do task_name=$(basename "$task_dir")

Read summary from task.md

summary=$(sed -n '/## Summary/,/##/p' "$task_dir/task.md" | head -n -1 | tail -n +2)

Determine category from task name or content

if echo "$task_name" | grep -qi "fix|bug"; then category="Fixed" elif echo "$task_name" | grep -qi "add|new|create"; then category="Added" else category="Changed" fi
echo "### $category" echo "- $summary (task: $task_name)" echo "" done

---
echo "## Changes from completed tasks" echo ""
for task_dir in docs/todo/done/*/; do task_name=$(basename "$task_dir")

Read summary from task.md

summary=$(sed -n '/## Summary/,/##/p' "$task_dir/task.md" | head -n -1 | tail -n +2)

Determine category from task name or content

if echo "$task_name" | grep -qi "fix|bug"; then category="Fixed" elif echo "$task_name" | grep -qi "add|new|create"; then category="Added" else category="Changed" fi
echo "### $category" echo "- $summary (task: $task_name)" echo "" done

---

Example CHANGELOG.md

示例 CHANGELOG.md

markdown
undefined
markdown
undefined

Changelog

Changelog

All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[Unreleased]

Added

Added

  • Dark mode toggle in settings (#234)
  • Keyboard shortcuts for navigation (#235)
  • Dark mode toggle in settings (#234)
  • Keyboard shortcuts for navigation (#235)

Changed

Changed

  • Improved search performance with MiniSearch (#236)
  • Improved search performance with MiniSearch (#236)

[2.0.0] - 2026-02-01

[2.0.0] - 2026-02-01

Added

Added

  • Steam OAuth authentication (#123)
  • Global fuzzy search (#124)
  • Card variant system with Condensed views (#126)
  • Steam OAuth authentication (#123)
  • Global fuzzy search (#124)
  • Card variant system with Condensed views (#126)

Changed

Changed

  • BREAKING: Renamed Monster to Creature throughout API (#127)
    • All 
      /api/monsters/*
      endpoints now at 
      /api/creatures/*
    • Frontend components renamed accordingly
    • See migration guide
  • BREAKING: Renamed Monster to Creature throughout API (#127)
    • All 
      /api/monsters/*
      endpoints now at 
      /api/creatures/*
    • Frontend components renamed accordingly
    • See migration guide

Fixed

Fixed

  • Null response crash in legacy API handler (#125)
  • Image flash on card hover (#128)
  • Null response crash in legacy API handler (#125)
  • Image flash on card hover (#128)

Security

Security

  • Updated dependencies to patch CVE-2026-1234 (#129)
  • Updated dependencies to patch CVE-2026-1234 (#129)

[1.1.0] - 2026-01-15

[1.1.0] - 2026-01-15

Added

Added

  • User profile page (#101)
  • Campaign management (#102)
  • User profile page (#101)
  • Campaign management (#102)

Fixed

Fixed

  • Login redirect loop (#103)
  • Login redirect loop (#103)

[1.0.0] - 2026-01-01

[1.0.0] - 2026-01-01

Added

Added

  • Initial release
  • User authentication (Google, Discord)
  • Creature compendium
  • Item database
  • Spell reference
  • Character builder

---
  • Initial release
  • User authentication (Google, Discord)
  • Creature compendium
  • Item database
  • Spell reference
  • Character builder

---

Best Practices

最佳实践

Do

建议

  • Write for users, not developers
  • Use past tense ("Added" not "Add")
  • Include issue/PR numbers
  • Highlight breaking changes clearly
  • Keep entries concise but informative
  • Update changelog with every PR
  • Group related changes
  • 为用户而非开发者撰写
  • 使用过去式（"Added"而非"Add"）
  • 包含Issue/PR编号
  • 明确标记破坏性变更
  • 条目简洁且信息充足
  • 每个PR都更新变更日志
  • 相关变更分组展示

Don't

避免

  • Include internal implementation details
  • Use technical jargon users won't understand
  • Forget to update links at bottom
  • Let [Unreleased] get too long (release often)
  • Mix user-facing and internal changes
  • Skip security updates
  • 包含内部实现细节
  • 使用用户无法理解的技术术语
  • 忘记更新底部的链接
  • 让[Unreleased]部分过于冗长（频繁发布）
  • 混合用户可见变更与内部变更
  • 遗漏安全更新

Integration with CI

与CI集成

Changelog Validation

变更日志验证

yaml
undefined
yaml
undefined

.github/workflows/changelog.yml

.github/workflows/changelog.yml

name: Changelog Check
on: pull_request: types: [opened, synchronize]
jobs: changelog: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - name: Check changelog updated
    run: |
      if git diff --name-only origin/main | grep -q "CHANGELOG.md"; then
        echo "Changelog updated"
      else
        echo "WARNING: CHANGELOG.md not updated"
        echo "Please add an entry under [Unreleased]"
        # Optionally fail: exit 1
      fi
undefined
name: Changelog Check
on: pull_request: types: [opened, synchronize]
jobs: changelog: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - name: Check changelog updated
    run: |
      if git diff --name-only origin/main | grep -q "CHANGELOG.md"; then
        echo "Changelog updated"
      else
        echo "WARNING: CHANGELOG.md not updated"
        echo "Please add an entry under [Unreleased]"
        # Optionally fail: exit 1
      fi
undefined

Auto-Release Notes

自动生成发布说明

yaml
undefined
yaml
undefined

.github/workflows/release.yml

.github/workflows/release.yml

name: Release
on: push: tags: - "v*"
jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - name: Extract changelog
    id: changelog
    run: |
      VERSION=${GITHUB_REF#refs/tags/v}
      # Extract section for this version
      NOTES=$(sed -n "/## \[${VERSION}\]/,/## \[/p" CHANGELOG.md | head -n -1)
      echo "notes<<EOF" >> $GITHUB_OUTPUT
      echo "$NOTES" >> $GITHUB_OUTPUT
      echo "EOF" >> $GITHUB_OUTPUT

  - name: Create Release
    uses: actions/create-release@v1
    with:
      tag_name: ${{ github.ref }}
      release_name: Release ${{ github.ref }}
      body: ${{ steps.changelog.outputs.notes }}

---
name: Release
on: push: tags: - "v*"
jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4
  - name: Extract changelog
    id: changelog
    run: |
      VERSION=${GITHUB_REF#refs/tags/v}
      # Extract section for this version
      NOTES=$(sed -n "/## \[${VERSION}\]/,/## \[/p" CHANGELOG.md | head -n -1)
      echo "notes<<EOF" >> $GITHUB_OUTPUT
      echo "$NOTES" >> $GITHUB_OUTPUT
      echo "EOF" >> $GITHUB_OUTPUT

  - name: Create Release
    uses: actions/create-release@v1
    with:
      tag_name: ${{ github.ref }}
      release_name: Release ${{ github.ref }}
      body: ${{ steps.changelog.outputs.notes }}

---

Signal Files

信号文件

For tracking changelog state:
SignalLocationContent
.changelog_version
Project rootLast released version
.needs_changelog
PR folderPR needs changelog entry
用于跟踪变更日志状态：
信号文件位置内容
.changelog_version
项目根目录上一个已发布的版本号
.needs_changelog
PR文件夹该PR需要添加变更日志条目

Changelog Checklist

变更日志检查清单

When adding entries:
  • Entry is under [Unreleased]
  • Correct category (Added/Changed/Fixed/etc.)
  • Written for end users
  • Includes issue/PR number
  • Breaking changes marked with BREAKING
  • Migration notes linked if needed
When releasing:
  • Version follows semver
  • Date is correct (YYYY-MM-DD)
  • All entries are accurate
  • Links updated at bottom
  • Empty [Unreleased] section remains
  • Git tag matches version
添加条目时：
  • 条目位于[Unreleased]部分下
  • 分类正确（Added/Changed/Fixed等）
  • 面向终端用户撰写
  • 包含Issue/PR编号
  • 破坏性变更标记有BREAKING
  • 必要时链接迁移指南
发布版本时：
  • 版本号遵循SemVer规范
  • 日期格式正确（YYYY-MM-DD）
  • 所有条目准确无误
  • 底部链接已更新
  • 保留空的[Unreleased]部分
  • Git标签与版本号匹配