github changelog generator

github-changelog生成器

• ChangElog的一代从未如此简单
• 更改的重点是什么？
• 我为什么要关心？
• 安装
• 用法
  • 与CLI一起运行：
  • 与Docker一起跑步
• 输出示例
  • 参数
  • 参数文件
  • github令牌
• 从手动变形符中迁移
  • 耙任务
• 该项目的功能和优势
  • 使用摘要部分功能
  • 替代方案
  • 使用此库的项目
• 实际用例
  • 创建GitHub发行说明
• 我是否缺少一些基本功能？
• 常问问题
• 贡献
• 联系我们
• 执照

ChangElog的一代从未如此简单

完全自动化的ChangElog生成- 此GEM根据标签，问题和合并的拉请请求（并根据标签将其分成单独的列表）生成一个更改文件文件。

由于您现在不必手动填充CHANGELOG.md ：只需运行脚本，放松一下，然后在下一个版本之前拿一杯☕！ ？

更改的重点是什么？

为了使用户和贡献者更容易查看项目的每个版本（或版本）之间已经进行了什么显着更改。

我为什么要关心？

因为软件工具适合人们。 “更改程序使用户和贡献者更容易确切查看项目的每个版本（或版本）之间已经进行了什么明显的更改。”

➡️https: //keapeachangelog.com

安装

GitHub ChangElog Generator是一个红宝石程序，分布成红宝石。 Ruby语言首页具有安装页面。

像以下方式安装宝石：

 $ gem install github_changelog_generator

根据系统的不同，您可能需要以管理员（Windows）的形式运行外壳，或使用sudo gem install github_changelog_generator （linux）。

用法

与CLI一起运行：

   github_changelog_generator -u github_project_namespace -p github_project

（如果您拥有的项目，则可能是您的用户名，但它也可能是项目的名称空间）

与Docker一起跑步

使用Docker是安装Ruby和Gem的替代方法。

示例调用：

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

• 对于GitHub企业存储库，请同时指定--github-site和--github-api选项：

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

这会生成一个CHANGELOG.md ，并具有漂亮的降价格式。

输出示例

• 查看该项目的changelog.md

• ActionHeetPicker-3.0/changelog.md是由命令生成的：

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

• 通常，看起来像这样：

1.2.5（2015-01-15）

完整的变换

实施增强：

• 使用里程碑来指定修复了哪个版本错误＃22

修复错误：

• 试图生成无标签库存日志时的错误

合并拉的请求：

• 使用小写“ PP”＃43（Schwing）包括PrettyPrint类

• 通过命令行选项＃42（Glenlovett）支持Enterprise GitHub

参数

打印所有命令行选项的帮助，以了解更多详细信息：

 $ github_changelog_generator --help

有关参数的更多详细信息，请阅读Wiki页面：高级ChangElog生成示例

参数文件

在您的项目root中，您可以将一个名为.github_changelog_generator的参数文件覆盖默认参数：

例子：

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

github令牌

Github每小时只允许50个未经验证的请求。

因此，建议通过使用令牌运行该脚本。

以下是：

• 在此处生成一个令牌 - 您只需要私人存储库的“ repo”范围
• 任何一个：
  • 用--token <your-40-digit-token>运行脚本;或者
  • 将CHANGELOG_GITHUB_TOKEN环境变量设置为40数字令牌

您可以通过在提示符下运行以下命令或将其添加到shell配置文件（例如， .env ， ~/.bash_profile ， ~/.zshrc等）来设置环境变量：

 export CHANGELOG_GITHUB_TOKEN="«your-40-digit-github-token»"

因此，如果您收到这样的消息：

API rate limit exceeded for github_username.
See: https://developer.github.com/v3/#rate-limiting

是时候创建这个令牌了！ （或者，请等待一个小时以重置您的未经身份验证的请求限制。）

从手动变形符中迁移

知道您对项目的敬业度，您可能没有等待github-changelog-generator来保留更改。但是，您可能也不希望您的项目的开放性问题和PRS适用于历史悠久的ChangElog中列出的所有过去功能。

那就是--base <your-manual-changelog.md>派上用场的地方！此选项使您的旧手动变形值将其附加到生成的条目的末尾。

如果您的项目中有一个HISTORY.md文件，则将自动选择作为静态历史变形值并附加。

耙任务

你爱rake吗？我们也这样做！因此，我们使您更容易：我们为您的ChangElog生成提供了一个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

所有命令行选项都可以作为config参数传递给rake Task。而且，由于您自己命名了rake任务，因此您可以根据需要创建任务。

您可以从解析器源代码（#setup_parser）中查找参数名称。例如，要将错误标签转换为葡萄牙语，而不是设置config.bugs_label ，您必须设置config.bug_prefix ，依此类推。

该项目的功能和优势

• 生成规范的，整洁的变形文件，其中包含遵循基本ChangElog指南的默认部分？

• 可选会产生未发布的更改（尚未发布的封闭问题）？

• GitHub企业通过命令行选项支持！ ？

• 灵活格式自定义：

  • 自定义应添加到ChangElog✳️的问题
  • 支持的自定义日期格式（但请记住ISO 8601！）？
  • 通过给问题的milestone与版本的标签相同的名称，手动指定解决问题的版本（对于问题的关闭日期不匹配）？
  • 自动排除与ChangElog无关的特定问题（默认情况下，任何标记为question ， duplicate ， invalid wontfix ）✂️

• 通过标签区分问题。 ？

  • 合并的拉请请求（所有合并的plup要求）？
  • 错误修复（标有bug问题）？
  • 增强功能（标有enhancement的问题）？
  • 问题（没有标签的封闭问题）？
  • 加上您想要的任何其他自定义标签到截面映射

• 手动包含或排除标签问题？

• 自定义更多！调整ChangElog以适合您的喜好？ （有关详细信息，请参见github_changelog_generator --help ）

使用摘要部分功能

对于每个版本，您可以添加带有文本，图像，gif动画等的发行摘要，并清楚地向用户显示新功能和注释。这是使用github元数据完成的。

示例：添加v1.0.0的版本摘要：

1. 创建一个新的GitHub问题
2. 在问题的描述字段中，添加您的发布摘要内容

 ![image](https://images.downcodes.com/uploads/20250603/img_683ee40fdcca131.png)

Hello, World! :tada:

3. 设置问题标签release-summary然后将其添加到GitHub Milestone v1.0.0
4. 关闭问题并执行github-changelog-generator
5. 结果看起来像这样：

V1.0.0（2014-11-07）

完整的变换

你好世界！ ？

实施增强：

• 添加一些功能

替代方案

这是我发现的Wikipage列表。但是没有人满足我的要求。

如果您知道其他项目，请随时编辑此Wiki页面！

使用此库的项目

这是Wikipage项目列表。

如果您在实时应用程序中使用了此项目，请告诉我！没有什么比看到别人拿起我的工作并与之狂奔更快乐的事情。

如果您使用github_changelog_generator来生成项目的变形值，或者知道使用它的其他项目，请将其添加到此列表中。

实际用例

创建GitHub发行说明

github_changelog_generator可以与github cli结合使用以创建发行说明。使用github_changelog_generator的--since-tag和--output选项为当前版本创建一个变形值，然后将结果存储在文件中。在下面的示例中，版本2.0.0是当前版本，版本1.0.0是先前的版本。

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

然后使用github cli的发行版创建功能创建新的github版本

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

我是否缺少一些基本功能？

• 没有什么是不可能的！

• 打开一个问题，让我们一起使发电机更好！

• 总是欢迎错误报告，功能请求，补丁和祝福。 ❗

常问问题

• 我已经使用了github版本。为什么我需要这个？

Github发行是一件非常好的事情。维护它是一个很好的做法。 （还没有很多人在使用它！）㊗️

顺便说一句：我想在接下来的发行版中支持GitHub发行;）

我不是要比较手写和自动生成的日志的质量。就是说...

即使您手动填写发行说明，自动生成的Changelog也确实有帮助！

• 我想定义自己的标签到部分映射，我该怎么做？

使用.github_changelog_generator中的add-sections或configure-sections条目，这是可能的。例如，要添加一个称为“维护”的单个新条目，该条目将捕获带有maintenance标签标记的PRS，您可以添加到.github_changelog_generator the行：

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

可以通过configure-sections使用类似的方法来设置所有部分属性（包括添加新的属性！）。

• 我的红宝石版本很旧，我可以使用吗？

当您的Ruby旧时，您不想升级，并且您想控制使用的库，则可以使用Bundler。

在一个杰夫里（Gemfile）中，也许在一个无人研究的:development小组中，添加这个宝石：

 group :development do
  gem 'github_changelog_generator' , require : false
end

然后，您可以保留诸如架子之类的依赖关系，后者当前仅与Ruby> = 2.2.2兼容。因此，通过在Gemfile中添加类似的行来为您的应用使用旧版本：

 gem 'rack', '~> 1.6'

这样，即使您无法安装最新版本的Ruby版本，也可以继续使用GitHub_changelog_generator。

• Windows：1.14.x希望在无效的路径上创建文件。为什么？

Windows：V1.14.0引入了一个错误，它尝试创建 /tmp/github_changelog-logger.log ...这不是Windows上的有效路径，因此失败

解决方法：创建C:tmp 。

贡献

您想为这个项目做出贡献吗？贡献。md具有有关如何做到这一点的所有详细信息。

联系我们

加入Gitter的聊天：GitHub-Changelog-Generator

执照

GitHub ChangElog发电机是根据MIT许可证发布的。