如何快速生成专业的GitHub项目更新日志：github-changelog-generator完整指南

【免费下载链接】github-changelog-generator Automatically generate change log from your tags, issues, labels and pull requests on GitHub. 项目地址: https://gitcode.com/gh_mirrors/gi/github-changelog-generator

GitHub Changelog Generator是一款强大的工具，能够根据GitHub上的标签、问题和合并的拉取请求自动生成清晰的更新日志文件。它将这些信息按照标签分类，让开发者能够轻松维护项目的变更记录，无需手动编写繁琐的更新日志。

为什么需要自动生成更新日志？

对于任何开源项目来说，一份清晰、规范的更新日志都是不可或缺的。它能帮助用户和贡献者准确了解每个版本之间的重要变更，提升项目的透明度和可维护性。然而，手动编写更新日志不仅耗时费力，还容易遗漏重要信息。GitHub Changelog Generator正是为解决这一痛点而生，让开发者能够专注于代码开发，而非繁琐的文档编写。

安装步骤：快速开始使用

GitHub Changelog Generator是一个Ruby程序，以RubyGem的形式分发。首先需要确保你的系统中安装了Ruby环境。然后通过以下命令安装gem：

gem install github_changelog_generator

根据你的系统，可能需要以管理员身份运行（Windows），或者使用sudo命令（Linux）：

sudo gem install github_changelog_generator

如果你不想安装Ruby环境，也可以使用Docker来运行：

docker run -it --rm -v "$(pwd)":/usr/local/src/your-app githubchangeloggenerator/github-changelog-generator

基本使用方法：生成你的第一份更新日志

使用GitHub Changelog Generator非常简单，基本命令格式如下：

github_changelog_generator -u github_project_namespace -p github_project

其中，github_project_namespace通常是项目所有者的用户名，github_project是项目名称。例如，要为名为"ActionSheetPicker-3.0"的项目生成更新日志，可以运行：

github_changelog_generator -u github-changelog-generator -p ActionSheetPicker-3.0

对于GitHub Enterprise仓库，需要指定--github-site和--github-api选项：

github_changelog_generator --github-site="https://github.yoursite.com" \
                           --github-api="https://github.yoursite.com/api/v3/"

运行命令后，会在当前目录下生成一个CHANGELOG.md文件，包含格式化的更新日志。

高级功能：定制你的更新日志

GitHub Changelog Generator提供了丰富的参数选项，可以根据项目需求定制更新日志的生成方式。通过运行以下命令可以查看所有可用选项：

github_changelog_generator --help

使用参数文件

在项目根目录下，可以创建一个名为.github_changelog_generator的参数文件来覆盖默认设置。例如：

unreleased=false
future-release=5.0.0
since-tag=1.0.0

GitHub令牌设置

GitHub对未认证请求有每小时50次的限制，因此建议使用令牌进行认证。生成令牌的步骤如下：

1. 在GitHub上生成一个令牌（需要"repo"作用域用于私有仓库）
2. 运行命令时使用--token <your-40-digit-token>选项，或者
3. 设置环境变量：export CHANGELOG_GITHUB_TOKEN="your-40-digit-github-token"

自定义标签到章节的映射

你可以通过.github_changelog_generator文件中的add-sections或configure-sections条目自定义标签到章节的映射。例如，添加一个"Project maintenance"章节：

add-sections= {"maintenance":{"prefix":"**Project maintenance**","labels":["maintenance"]}}

实际应用场景：与GitHub Release结合使用

GitHub Changelog Generator可以与GitHub CLI结合使用，创建发布说明。以下是一个示例工作流：

1. 生成当前版本的更新日志：

mkdir -p build
github_changelog_generator \
  --since-tag 1.0.0 \
  --output build/changelog.md

2. 使用GitHub CLI创建新的发布：

gh release create 2.0.0 \
  --notes-file build/changelog.md \
  --title 2.0.0

Rake任务集成：无缝融入开发流程

如果你使用Rake，可以将更新日志生成集成到项目的Rake任务中。在Rakefile中添加以下配置：

require 'github_changelog_generator/task'

GitHubChangelogGenerator::RakeTask.new :changelog do |config|
  config.user = 'username'
  config.project = 'project-name'
  config.since_tag = '0.1.14'
  config.future_release = '0.2.0'
end

然后运行rake changelog即可生成更新日志。

总结：提升项目效率的必备工具

GitHub Changelog Generator通过自动化更新日志的生成过程，大大减轻了开发者的负担，同时确保了更新日志的准确性和一致性。无论是小型个人项目还是大型企业级应用，都能从中受益。

主要优势包括：

• 遵循Keep a Changelog规范的默认章节
• 支持GitHub Enterprise
• 灵活的格式自定义选项
• 基于标签的问题分类
• 与GitHub Release无缝集成

如果你还在手动维护项目的更新日志，不妨尝试使用GitHub Changelog Generator，让开发流程更加高效！

要开始使用，只需克隆仓库并按照安装指南操作：

git clone https://gitcode.com/gh_mirrors/gi/github-changelog-generator

更多详细信息和高级用法，请参考项目的README.md和CONTRIBUTING.md文件。

【免费下载链接】github-changelog-generator Automatically generate change log from your tags, issues, labels and pull requests on GitHub. 项目地址: https://gitcode.com/gh_mirrors/gi/github-changelog-generator