JMESLog - 变更日志管理

源代码: https://github.com/jamesls/jmeslog PyPI: https://pypi.ac.cn/project/jmeslog/

JMESLog是一个用于管理变更日志的脚本。它帮助您关联新功能和错误修复的变更日志条目，并帮助您生成CHANGELOG文件或其他类型的发布说明页面。它通过根据您下一次发布的待处理更改自动确定下一个版本号来强制执行semver。

安装

pip install jmeslog

快速入门

初始化一个仓库以使用JMESLog

$ jmeslog init

在您发送PR之前，为您的更改创建一个变更日志条目

$ jmeslog new-change

A change file was created at .changes/next-release/foo-bar.json

提交该文件

$ git add .changes/next-release/foo-bar.json
$ git commit -m "Add changelog entry"

就是这样。到发布时间，您将运行以下命令

$ jmeslog new-release
$ jmeslog render > CHANGELOG.rst

new-release 命令将 .changes/next-release 目录中的所有文件合并成一个表示新版本的单一JSON文件。 render 命令将重新生成您的CHANGELOG文件。

本文档的其余部分将更详细地解释此工作流程。

概念

一个仓库的所有更改都存储在 .changes/ 目录中的结构化数据中。

下一次发布的更改存储在 .changes/next-release/。所有以前版本的更改都存储在 .changes/X.Y.Z.json 中，其中 X.Y.Z 代表与给定版本关联的版本。这些文件通过运行 jmeslog new-change 命令生成。

当您准备发布新版本时，从 .changes/next-release/ 目录中收集所有变更文件，并创建一个包含这些变更的新 .changes/X.Y.Z.json 文件。然后，从 .changes/next-release/ 中删除内容。这是通过 jmeslog new-release 命令完成的。

然后，您可以使用 .changes/ 中的数据生成 CHANGELOG（或任何其他文件）。为此，您运行 jmeslog generate 命令。

用法

使用 jmeslog 的典型工作流程

• 当您正在开发新功能时，使用 jmeslog new-change 命令生成新的变更日志文件。此文件作为您发送的 PR 的一部分包含在内。
• 准备好发布时，您可以运行 jmespath generate 命令，根据所有变更文件生成 CHANGELOG 文件。您还可以运行 jmeslog new-release 命令，将 .changes/next-release/ 目录中的文件合并到一个新的单个 .changes/X.Y.Z.json 文件中。

渲染变更日志

默认情况下，jmeslog render 命令以 RST 格式渲染 CHANGELOG 文件，具有以下结构

=========
CHANGELOG
=========

X.Y.Z
=====

* type:category:description

您可以通过指定自己的模板来控制更改的渲染方式。要指定自己的模板，首先创建一个 .changes/templates 目录

mkdir .changes/templates

然后创建您想要的任何数量的模板。例如

touch .changes/templates/MYTEMPLATE

这个名称可以是您想要的任何名称。接下来，您编写模板。模板使用 jinja2 编写。

模板在渲染变更日志时提供了以下上下文字典

{
  "changes": [
    ("x.y.z": [{"type": "", "category": "", "description": ""}, ...]),
    ("x.y.z - 1": [{"type": "", "category": "", "description": ""}, ...]),
    ("x.y.z - 2": [{"type": "", "category": "", "description": ""}, ...]),
  ]
}

changes 列表按降序排列，最新版本排在第一位，最旧版本排在 changes 列表的最后。

要使用此模板，指定文件名（基本名称，而不是整个文件名）作为 --template 参数。例如，如果您的模板文件是 .changes/templates/MYTEMPLATE，则指定 jmeslog render --template MYTEMPLATE。

以下是如果没有提供 --template 参数则使用的默认模板

=========
CHANGELOG
=========

{% for release, changes in releases %}
{{ release }}
{{ '=' * release|length }}
{% if changes.summary %}
{{ changes.summary -}}
{% endif %}
{% for change in changes.changes %}
* {{ change.type }}:{{ change.category }}:{{ change.description }}
{% endfor %}
{% endfor %}

向后兼容性

以下内容在 1.0.0 GA 发布之前可能会以向后不兼容的方式更改

• CLI 命令和参数
• .changes/ 下生成的文件
• JMESLog 提供的功能
• 提供给自定义模板的上下文字典

常见问题解答

这个试图解决什么问题？

JMESLog 帮助您自动化发布。它是从完全手动过程开始，最终每天发布每个版本，迭代自动化发布过程的结果。当您考虑发布您库/工具新版本所涉及的内容时，您必须

• 确定您想要发布的下一个版本号。如果您遵循 semver，这将取决于下一个版本中包含哪些类型的更改。新功能应该需要增加次版本号，而错误修复应该导致新的补丁版本。
• 更新您的 CHANGELOG，在对应下一个版本号的新部分下添加所有将包含在此下一个版本中的新更改。

此工具帮助解决这两个问题，以便您可以完全自动化您的发布过程。它还解决了其他一些问题

• 您可以将每个拉取请求的变更日志条目跟踪下来，而无需担心合并冲突到您的 CHANGELOG 文件中。
• 如果需要，您还可以生成不仅仅是 CHANGELOG 文件。例如，您可以在文档中创建一个渲染方式不同于 CHANGELOG 的“历史”页面。
• 您可以通过编程方式查询项目的变更。

开发

此项目需要 Python 3.9+ 并使用 Poetry 管理依赖项。

创建并激活虚拟环境后，运行

poetry install

这将安装所有必要的依赖项，并以可编辑模式安装此项目。

测试

Poe the Poet 是用于此项目的任务运行器，它是作为 poetry install 步骤的一部分自动安装的。要查看可用任务的列表，请在不带参数的情况下运行 poe 命令。

要为此项目运行测试，请运行

poe test

预提交

Pre-commit 挂钩运行各种自动格式化和质量检查，以确保所有更改在提交之前看起来都很好。相同的更改也会在拉取请求上运行，这有助于在提交拉取请求之前提供更快的反馈循环。

您可以使用以下命令安装挂钩（每次提交都运行）

pre-commit install

或者如果您想例如手动运行所有检查的所有文件

poe pre-commit

或者如果您直接运行 pre-commit 可执行文件

pre-commit run --all-files