ponylang/changelog-tool

changelog-tool

概述

changelog-tool 是一个用于处理 "标准pony" 变更日志的工具，支持创建、验证、管理变更日志条目及版本发布准备等操作，帮助开发者遵循语义化版本（Semantic Versioning）和 Keep a CHANGELOG 规范维护项目变更记录。

核心功能

• 创建新的变更日志文件
• 验证现有变更日志的有效性
• 提取并打印指定版本的变更日志内容
• 添加未发布版本的变更记录区域
• 向未发布区域添加具体变更条目（新增、修复、变更等类型）
• 准备发布版本，将未发布内容转换为正式版本记录并生成新的未发布区域

使用场景

适用于 Pony 语言项目的开发过程，帮助开发团队标准化变更日志的管理，尤其适合需要严格遵循语义化版本和变更日志规范的项目，简化版本迭代中的变更记录维护工作。

使用方法

前提条件

使用时需将包含变更日志文件（CHANGELOG.md）的项目目录挂载到容器中，确保工具可访问并修改目标文件。

创建变更日志

生成新的 CHANGELOG.md 文件：

bash
docker run --rm -v $(pwd):/app docker.xuanyuan.run/changelog-tool new

验证变更日志

检查现有 CHANGELOG.md 的格式和内容有效性：

bash
docker run --rm -v $(pwd):/app docker.xuanyuan.run/changelog-tool verify

验证成功输出示例：

CHANGELOG.md is a valid changelog.

打印单个版本的变更日志

提取并显示指定版本的变更内容：

bash
docker run --rm -v $(pwd):/app docker.xuanyuan.run/changelog-tool get 0.2.2

输出示例：

markdown
## [0.2.2] - 2018-01-16

### Added

- Many prior version. This was added as first entry in CHANGELOG when it was added to this project.

添加未发布部分

在变更日志顶部创建新的未发布（unreleased）区域：

bash
docker run --rm -v $(pwd):/app docker.xuanyuan.run/changelog-tool unreleased -e

注：-e 参数表示直接修改文件（edit mode）

向未发布部分添加条目

向未发布区域添加具体变更类型的条目（支持 added/fixed/changed 等类型）：

bash
# 添加修复类条目
docker run --rm -v $(pwd):/app docker.xuanyuan.run/changelog-tool add fixed "We fixed some bad issues" -e

# 添加新增类条目
docker run --rm -v $(pwd):/app docker.xuanyuan.run/changelog-tool add added "We just added some new cool stuff" -e

# 添加变更类条目
docker run --rm -v $(pwd):/app docker.xuanyuan.run/changelog-tool add changed "And changed things a bit" -e

准备发布版本

将未发布内容转换为指定版本的正式记录，并生成新的未发布区域：

bash
# 查看发布预览（不修改文件）
docker run --rm -v $(pwd):/app docker.xuanyuan.run/changelog-tool release 0.13.1

# 执行发布并修改文件（推荐）
docker run --rm -v $(pwd):/app docker.xuanyuan.run/changelog-tool release 0.13.1 -e

发布前后示例对比

发布前的 CHANGELOG.md：

markdown
# Change Log

All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/) and [Keep a CHANGELOG](http://keepachangelog.com/).

## [unreleased] - unreleased

### Fixed



### Added

- We are only adding things on this release

### Changed

发布后的 CHANGELOG.md：

markdown
# Change Log

All notable changes to the Pony compiler and standard library will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/) and [Keep a CHANGELOG](http://keepachangelog.com/).

## [0.13.1] - 2017-04-14

### Added

- We are only adding things on this release

## [unreleased] - unreleased

### Fixed



### Added



### Changed

注意：发布后会自动在顶部创建新的未发布区域，且仅保留原未发布区域中有内容的部分（示例中仅保留 Added 部分）。