您对项目和文档的结构化和记录方式是个人化的，并随着时间的推移演变成最适合您和您社区的方式。 Jilu 试图提供一种简单且美观的方式将项目变更展示给外界。它是灵活的，但永远不能取代所有可能的流程，它也从不假装能。

使用 Jilu 需要使用 约定提交，尽管有些人喜欢结构化提交的严谨性，而有些人则不然，两种都有其合理的理由。如果您已经有了适合自己的工作流程，或者现有的项目没有使用约定提交，那么在这里您可能不会获得太多收获。

最重要的是您项目的成功，无论是否有 Jilu 的帮助。

快速开始

1. 查看本项目的 变更日志。

2. 安装 jilu

   • 使用 发布二进制文件

     curl -L https://github.com/rustic-games/jilu/releases/download/v0.3.0/jilu_0.3.0_$(uname)_x86_64.tar.gz | tar -xvf - jilu
     

   • 使用 Homebrew （即将推出）

     brew install jilu
     

   • 使用 Cargo

     cargo install jilu --git https://github.com/rustic-games/jilu
     

3. 访问任何本地仓库

   cd /path/to/repository
   

4. 打印变更日志

   jilu
   

5. 获取更多详细信息 （即将推出）

   jilu --help
   

6. 集成到您的 CI 工作流程。

关于

作为一名《常规提交》的粉丝，同时也是开源变更日志的忠实读者，当看到缺失变更日志或缺乏重要上下文细节时，我总是感到非常沮丧。例如，发布日期、未发布更改或破坏性更改都是项目公共文档的重要组成部分。除此之外，作为一名开源贡献者，当人们感谢我的贡献时，我会感到一种温暖而舒适的感觉，但跟踪所有这些贡献会占用你用于项目的时间 （不过，自动感谢并不像个人感谢那样个性化，请记住这一点）。

常规提交和自动生成的变更日志在JavaScript社区中非常受欢迎，有很多 工具 帮助你遵循标准，但我尝试过的所有工具都有缺点，最大的缺点是缺乏单个二进制文件、缺乏易于配置以及充斥着表情符号 （我并不介意一两个表情符号，但是请注意 ✌️），或者试图成为完整的发布管理工具，这不可避免地意味着它过于关注JavaScript生态系统 （并且不遵循Unix哲学中的小型单一用途工具）。

Jilu是我希望用来生成我的项目变更日志的工具，我已经将其开源，以便它也能帮助你在你的开源事业中。享受使用它，并请随时提出新功能，或提供错误修复！

用法

将jilu的输出通过管道传输到您的变更日志文件

jilu > CHANGELOG.md

注意，如果您已向变更日志添加了自定义配置，则此方法将不起作用，因为Unix会首先清空CHANGELOG.md文件，然后jilu才能读取其内容，这意味着它无法读取任何现有配置。

为了解决这个问题，使用像sponge这样的工具在重定向到文件之前吸收jilu的输出

jilu | sponge CHANGELOG.md

设计

想了解是什么让Jilu运转？请继续阅读。

结构化

该库使用现有的约定和规范来构建变更日志。具体来说，您应该使用SemVer来标记发布，使用常规提交来提交消息，并且变更日志本身遵循Keep a Changelog的约定。

自动化

通过解析Git历史记录来生成发布说明。克隆任何本地存储库，并运行jilu以打印生成的发布说明。

提交消息使用常规提交格式解析。

Git标签用于确定哪些提交应包含在哪些发布中。使用带注解的标签消息添加手写的发布说明。类似于常规提交，标签注释的第一行用作发布标题，其余部分用作发布说明。

在最新的标记发布之后的任何提交都将添加到“未发布”部分。

工作进行中 如果一个标签注释包含以 YANKED: 开头的行，它将在更改日志中被标记为这样的，而跟在标记之后的内容将用作撤回发布的原因。Git标签注释 [在推送后可以替换][]，同时保留标签日期和作者，使用一些命令行技巧。

如果您想生成一个包含未发布提交的新发布的更改日志，可以可选地运行 jilu --release MAJOR.MINOR.PATCH。当这样做时，您的 $EDITOR 将打开以提供发布说明。这还会创建一个包含相同详情的Git标签（除非您提供 --no-tag）。

添加发布功能是为了确保更新的更改日志成为新发布的一部分。否则，在发布标签处的仓库状态打开更改日志仍会显示 未发布 部分的新更改。

可读性

遵循 Keep a Changelog 指南的精神，jilu 通过包含以下信息生成人类可读的更改日志

• markdown 格式化以改进可读性
• 自定义更改日志简介段落
• 目录
• 顶部未发布更改
• 发布版本、标题和日期
• 按类型（功能、修复等）分组发布更改
• 手动编写的发布说明
• 链接特定提交的短git引用
• 可选感谢贡献者
• 可选GitHub链接到发布/标签/比较视图

宽容

需要排除的提交消息可以根据一组规则进行排除

• 非传统提交消息将被忽略
• 传统提交类型（如 chore）可以被排除
• 工作进行中 可以提供黑名单提交的列表
• 工作进行中 可以提供根提交以忽略较旧的提交

可配置

Jilu 有一个强大的配置系统，当您不需要时，它会保持不会打扰您，但允许您以最适合您项目或社区的方式自动构建更改日志。

您可以

• 为分组更改（功能、修复等）设置标题名称
• 忽略特定提交类型
• 完全自定义更改日志模板

您可以在此项目的更改日志底部查看其配置，以及默认模板以了解模板系统的工作方式。

以下是一个快速示例（此片段位于您的自己的 CHANGELOG.md 文件底部）

<!--
Config(
  github: ( repo: "rustic-games/jilu" ),
  accept_types: ["feat", "fix", "perf"],
  type_headers: {
    "feat": "Features",
    "fix": "Bug Fixes",
    "perf": "Performance Improvements"
  }
)

Template(
# My Change Log

## Upcoming Changes

{% for change in unreleased.changes %}
- {{ change.description }} ([`{{ change.commit.short_id }}`])
{%- endfor %}
)
-->

将配置 放在 更改日志文件内部确保配置可以被 Jilu 读取，但不会出现在markdown渲染的文档中，并且在文本格式中很容易忽略，因为它总是在更改日志的末尾。这也意味着您不需要在Git仓库根目录中添加 另一个 配置文件。

模板系统使用Tera库来提供类似Django的语法。如果没有定义模板，将使用默认模板。