unclog

疏通您的变更日志

从您项目.changelog文件夹中结构化的独立文件集合构建您的变更日志。这有助于避免在同时处理多个PR时出现令人烦恼的合并冲突。

假设您的变更日志将输出为Markdown格式。

为什么不用Git提交历史记录呢？

许多提供类似功能的其他工具专注于从项目的Git提交历史中提取变更日志条目。我们为什么不这样做呢？

我们发现针对每种类型的内容针对不同的受众群体很有价值，并且能够根据每个受众群体定制内容：Git提交历史用于我们的开发者，变更日志用于我们的用户。

要求

• 使用最新的Rust稳定版进行测试
• Git
• 您的项目托管在GitHub或GitLab上（用于从CLI自动生成变更日志条目）

安装

# Install to ~/.cargo/bin/
cargo install unclog

或者您可以从源代码构建

cargo install --git https://github.com/informalsystems/unclog.git

使用方法

示例.changelog文件夹

项目.changelog文件夹的一个示例布局如下

.changelog/                   - The project's .changelog folder, in the root of the repo.
|__ unreleased/               - Changes to be released in the next version.
|   |__ breaking-changes/     - "BREAKING CHANGES" section entries.
|   |   |__ 890-block.md      - An entry in the "BREAKING CHANGES" section.
|   |
|   |__ bug-fixes/            - "BUG FIXES" section entries.
|   |   |__ module1/          - "BUG FIXES" section entries specific to "module1".
|   |       |__ 745-rename.md - An entry in the "BUG FIXES" section under "module1".
|   |__ features/             - "FEATURES" section entries.
|   |
|   |__ summary.md            - A summary of the next release.
|
|__ v0.1.0/                   - Changes released historically in v0.1.0.
|   |__ breaking-changes/     - "BREAKING CHANGES" section entries for v0.1.0.
|   |   |__ 467-api.md        - An entry in the "BREAKING CHANGES" section for v0.1.0.
|   |   |__ 479-rpc.md        - Another entry in the "BREAKING CHANGES" section for v0.1.0.
|   |
|   |__ bug-fixes/            - "BUG FIXES" section entries for v0.1.0.
|   |
|   |__ summary.md            - A summary of release v0.1.0.
|
|__ epilogue.md               - Any content to be added to the end of the generated CHANGELOG.

更详细的示例请参考tests/full文件夹中的主要集成测试，该测试使用了最多的功能/功能。当构建tests/full文件夹中的文件时，tests/full/expected.md是预期的输出。

CLI

# Detailed information regarding usage.
unclog -h

初始化变更日志

# Creates a ".changelog" folder in the current directory.
unclog init

# Creates a ".changelog" folder in the current directory, and also copies your
# existing CHANGELOG.md into it as an epilogue (to be appended at the end of
# the final changelog built by unclog).
unclog init -e CHANGELOG.md

# Automatically generate a `config.toml` file for your changelog, inferring as
# many settings as possible from the environment. (Right now this mainly infers
# your GitHub project URL, if it's a GitHub project)
unclog init -g

添加新的未发布条目

添加新条目有两种方式

1. 完全通过CLI
2. 通过您的默认$EDITOR

要完全通过CLI添加条目

# First ensure your config.toml file contains the project URL:
echo 'project_url = "https://github.com/org/project"' >> .changelog/config.toml

# Add a new entry whose associated GitHub issue number is 23.
# Word wrapping will automatically be applied at the boundary specified in your
# `config.toml` file.
unclog add --id some-new-feature \
  --issue 23 \
  --section breaking-changes \
  --message "Some *new* feature"

# Same as above, but with shortened parameters
unclog add -i some-new-feature \
  -n 23 \
  -s breaking-changes \
  -m "Some *new* feature"

# If your project uses components/sub-modules
unclog add -i some-new-feature \
  -n 23 \
  -c submodule \
  -s breaking-changes \
  -m "Some *new* feature"

要使用您的最喜欢的$EDITOR

# First ensure that your $EDITOR environment variable is configured, or you can
# manually specify an editor binary path via the --editor flag.
#
# This will launch your configured editor and, if you add any content to the
# feature file it will be added to
# ".changelog/unreleased/features/23-some-new-feature.md".
#
# The convention is that you *must* prepend the issue/PR number to which the
# change refers to the entry ID (i.e. 23-some-new-feature relates to issue 23).
unclog add --section features --id 23-some-new-feature

# Add another feature in a different section
unclog add -s breaking-changes -i 24-break-the-api

条目的格式目前建议如下（Markdown格式）

- A user-oriented description of the change ([#123](https://github.com/someone/someproject/issues/123))

例如，#123及其对应的链接最好是解决该问题的链接。如果没有问题，则引用PR。

构建变更日志

# Run from your project's directory to build your '.changelog' folder.
# Builds your CHANGELOG.md and writes it to stdout. Does not build any
# unreleased entries.
unclog build

# Only render unreleased changes (returns an error if none)
unclog build --unreleased-only
unclog build -u

# Build all entries, both released and unreleased.
unclog build --all
unclog build -a

# Save the output as your new CHANGELOG.md file.
# NOTE: All logging output goes to stderr.
unclog build > CHANGELOG.md

# Increase output logging verbosity on stderr and build your `.changelog`
# folder.
unclog -v build

# Get help
unclog --help

发布新版本的变更集

# Moves all entries in your ".changelog/unreleased" folder to
# ".changelog/v0.2.0" and ensures the ".changelog/unreleased" folder is empty.
unclog release v0.2.0

组件/子模块

如果您的项目包含组件或子模块，则在创建变更日志条目时引用它们，可以使您将一个组件的条目分组在一起。例如

unclog add -i some-new-feature \
  -n 23 \
  -c submodule \
  -s breaking-changes \
  -m "Some *new* feature"

将在.changelog/unreleased/submodule/breaking-changes/23-some-new-feature.md中创建条目，当渲染时，将看起来像

- [submodule](./submodule)
  - Some *new* feature ([#23](https://github.com/org/project/issues/23))

注意：从v0.5.0版本开始，在尝试添加引用任何组件的条目之前，您必须先在配置文件中定义您的组件（见下文）。否则，unclog将失败。这是为了确保人们不会为错误命名的或不存在于组件添加条目。

重复检测

unclog有一个方便的方法来帮助您在本地分支的发布之间找到重复条目（根据#81，未来版本的目标是在Git仓库分支之间提供此功能）。

# List all the duplicate entries across releases.
unclog find-duplicates

配置

某些unclog设置可以通过在.changelog/config.toml中使用配置文件来覆盖。以下TOML显示了配置的所有默认值。如果您没有.changelog/config.toml文件，将假定所有默认值。

# The GitHub URL for your project.
#
# This is mainly necessary if you need to automatically generate changelog
# entries directly from the CLI. Right now we only support GitHub, but if
# anyone wants GitLab support please let us know and we'll try implement it
# too.
project_url = "https://github.com/org/project"

# The file to use as a Handlebars template for changes added directly through
# the CLI.
#
# Assumes that relative paths are relative to the `.changelog` folder. If this
# file does not exist, a default template will be used.
change_template = "change-template.md"

# The number of characters at which to wrap entries automatically added from
# the CLI.
wrap = 80

# The heading right at the beginning of the changelog.
heading = "# CHANGELOG"

# What style of bullet to use for the instances where unclog has to generate
# bullets for you. Can be "-" or "*".
bullet_style = "-"

# The message to output when your changelog has no entries yet.
empty_msg = "Nothing to see here! Add some entries to get started."

# The name of the file (relative to the `.changelog` directory) to use as an
# epilogue for your changelog (will be appended as-is to the end of your
# generated changelog).
epilogue_filename = "epilogue.md"

# Sort releases by the given property/properties. Possible values include:
# - `version` : Sort releases by semantic version.
# - `date`    : Sort releases by release date.
#
# This is an array, as one could potentially first sort by date and then version
# in cases where multiple releases were cut on the same date.
#
# Release dates are currently parsed from release summaries, and are expected to
# be located on the first line of the release summary.
sort_releases_by = ["version"]

# Release date formats to expect in the release summary, in order of precedence.
#
# See https://docs.rs/chrono/latest/chrono/format/strftime/index.html for
# possible format specifiers.
release_date_formats = [
    # "*December 1, 2023*
    "*%B %d, %Y*",
    # "*Dec 1, 2023*
    "*%b %d, %Y*",
    # "2023-12-01" (ISO format)
    "%F",
]


# Settings relating to unreleased changelog entries.
[unreleased]

# The name of the folder containing unreleased entries, relative to the
# `.changelog` folder.
folder = "unreleased"

# The heading to use for the unreleased entries section.
heading = "## Unreleased"


# Settings relating to sets (groups) of changes in the changelog. For example, a
# particular version of the software (e.g. "v1.0.0") is typically a change set.
[change_sets]

# The filename containing a summary of the intended changes. Relative to the
# change set folder (e.g. `.changelog/unreleased/breaking-changes/summary.md`).
summary_filename = "summary.md"

# The extension of files in a change set.
entry_ext = "md"


# Settings relating to all sections within a change set. For example, the
# "BREAKING CHANGES" section for a particular release is a change set section.
[change_set_sections]

# Sort entries by a particular property. Possible values include:
# - `id`         : The issue/PR number (the default value).
# - `entry-text` : The entry text itself.
sort_entries_by = "id"


# Settings related to components/sub-modules. Only relevant if you make use of
# components/sub-modules.
[components]

# The title to use for the section of entries not relating to a specific
# component.
general_entries_title = "General"

# The number of spaces to inject before each component-related entry.
entry_indent = 2

    # The components themselves. Each component has a name (used when rendered
    # to Markdown) and a path relative to the project folder (i.e. relative to
    # the parent of the `.changelog` folder).
    [components.all]
    component1 = { name = "Component 1", path = "component1" }
    docs = { name = "Documentation", path = "docs" }

作为库

默认情况下，启用了cli功能，它会构建CLI。要使用unclog作为库而不是CLI

[dependencies]
unclog = { version = "0.6", default-features = false }

许可证

版权所有© 2021-非正式系统及其贡献者

根据Apache许可证第2版（“许可证”）许可；除非遵守许可证规定，否则您不得使用此存储库中的文件。您可以在以下位置获得许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则根据许可证分发的软件按“原样”分发，不提供任何明示或暗示的保证或条件。有关许可证管理权限和限制的具体语言，请参阅许可证。