prepare-changelog

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Changelog Format Guide

更新日志格式指南

This document describes the format and conventions used in

site/src/changelog.md

本文档介绍了

site/src/changelog.md

中使用的格式与约定。

Overall Structure

整体结构

The changelog follows the Keep a Changelog format with nextest-specific conventions.

更新日志遵循Keep a Changelog格式，并结合了nextest专属约定。

Version Header

版本标题

markdown

undefined

markdown

undefined

[X.Y.Z] - YYYY-MM-DD


- Version numbers are in brackets
- Date is in ISO 8601 format (YYYY-MM-DD)
- Each version should have a corresponding link at the bottom of the file (though this is often omitted for newer entries)


- 版本号放在方括号内
- 日期采用ISO 8601格式（YYYY-MM-DD）
- 每个版本在文件底部应有对应的链接（不过新版本条目通常会省略这一点）

Section Organization

章节组织

Sections should appear in this order (only include sections that are relevant):

Added - New features
Changed - Changes to existing functionality
Fixed - Bug fixes
Deprecated - Soon-to-be removed features
Removed - Removed features
Security - Security-related changes
Known issues - Known problems with this release
Miscellaneous - Other notable changes that don't fit elsewhere
Internal improvements - Internal changes that may interest contributors

章节应按以下顺序排列（仅包含相关章节）：

Added - 新功能
Changed - 现有功能变更
Fixed - Bug修复
Deprecated - 即将移除的功能
Removed - 已移除的功能
Security - 安全相关变更
Known issues - 已知问题
Miscellaneous - 其他不适合归入其他章节的重要变更
Internal improvements - 可能对贡献者有意义的内部变更

Section Style

章节样式

Use
```
###
```
for section headers (e.g.,
```
### Added
```
)
Each section contains bullet points starting with
```
-
```
Indent sub-bullets with two spaces

使用
```
###
```
作为章节标题（例如：
```
### Added
```
）
每个章节包含以
```
-
```
开头的项目符号
子项目符号缩进两个空格

Content Guidelines

内容准则

What to Include

应包含的内容

User-visible changes and new features
Bug fixes that affect users
Performance improvements
Breaking changes (clearly marked)
MSRV (Minimum Supported Rust Version) changes
Security updates

用户可见的变更与新功能
影响用户的Bug修复
性能提升
破坏性变更（需明确标记）
MSRV（最低支持Rust版本）变更
安全更新

What to Exclude

应排除的内容

Internal dependency updates
Internal refactoring (unless it has user-visible effects)
Documentation-only changes to the site
CI/CD workflow changes
Dependency updates for minor versions (can be grouped)

内部依赖更新
无用户影响的内部重构
仅针对站点的文档变更
CI/CD工作流变更
小版本的依赖更新（可合并分组）

Writing Style

写作风格

Be concise but descriptive: Each bullet should clearly explain what changed and why it matters
Use present tense: "Nextest now supports..." not "Nextest now supported..."
Link to documentation: When introducing features, link to relevant docs with the full URL path
Include context: Explain the motivation or benefit when it's not obvious

简洁且描述清晰：每个项目符号应明确说明变更内容及其重要性
使用一般现在时：例如“Nextest现在支持……”而非“Nextest现在已支持……”
链接到文档：引入新功能时，使用完整URL路径链接到相关文档
包含上下文：当动机或优势不明显时，需进行解释

Examples

示例

Good:

markdown

- Nextest can now update itself! Once this version is installed, simply run `cargo nextest self update` to update to the latest version.

Good (with note to distributors):

markdown

- Nextest now sets `NEXTEST_LD_*` and `NEXTEST_DYLD_*` environment variables to work around macOS System Integrity Protection sanitization.
  > Note to distributors: ...

Good (with forward-looking context):

markdown

- A new `threads-required` configuration that can be specified as a per-test override. This can be used to limit concurrency for heavier tests, to avoid overwhelming CPU or running out of memory.

优秀示例：

markdown

- Nextest现在支持自我更新！安装此版本后，只需运行`cargo nextest self update`即可更新至最新版本。

优秀示例（含面向分发者的说明）：

markdown

- Nextest现在会设置`NEXTEST_LD_*`和`NEXTEST_DYLD_*`环境变量，以绕过macOS系统完整性保护的sanitization限制。
  > 面向分发者的说明：……

优秀示例（含前瞻性上下文）：

markdown

- 新增`threads-required`配置，可作为测试级别的覆盖项使用。此配置可用于限制重型测试的并发数，避免CPU过载或内存耗尽。

Links and References

链接与引用

PR and Issue Links

PR与Issue链接

Use inline links:
```
([#2618])
```

Define the link at the end of the section or version:

[#2618]: https://github.com/nextest-rs/nextest/pull/2618

For pull requests, use the
```
/pull/
```
URL
For issues, use the
```
/issues/
```
URL

使用内联链接：
```
([#2618])
```

在章节或版本末尾定义链接：

[#2618]: https://github.com/nextest-rs/nextest/pull/2618

对于Pull Request，使用
```
/pull/
```
格式的URL
对于Issue，使用
```
/issues/
```
格式的URL

External Links

外部链接

Use inline markdown links:
```
[text](URL)
```

Examples:

[GHSA-xxxx](https://github.com/advisories/GHSA-xxxx)

[CVE-xxxx](https://nvd.nist.gov/vuln/detail/CVE-xxxx)

使用内联Markdown链接：
```
[文本](URL)
```

示例：

[GHSA-xxxx](https://github.com/advisories/GHSA-xxxx)

、

[CVE-xxxx](https://nvd.nist.gov/vuln/detail/CVE-xxxx)

Contributor Attribution

贡献者署名

First-time Contributors

首次贡献者

Always thank first-time contributors using this format (use GitHub username only, not full name):

markdown

Thanks [username](https://github.com/username) for your first contribution!

Place the attribution:

At the end of the bullet point if it's a single change
At the end of the section if multiple related changes

Examples:

markdown

- New feature that does something. Thanks [alice](https://github.com/alice) for your first contribution!

markdown

undefined

务必使用以下格式感谢首次贡献者（仅使用GitHub用户名，而非全名）：

markdown

感谢 [username](https://github.com/username) 提交首次贡献！

署名位置：

若为单一变更，放在项目符号末尾
若为多个相关变更，放在章节末尾

示例：

markdown

- 新增某项功能。感谢 [alice](https://github.com/alice) 提交首次贡献！

markdown

undefined

Added

Feature A
Feature B

Thanks bob for your first contribution!

undefined

功能A
功能B

感谢 bob 提交首次贡献！

undefined

Returning Contributors

重复贡献者

For contributors who have contributed before, you can optionally thank them but don't say "first contribution":

markdown

Thanks [charlie](https://github.com/charlie) for your contribution!

Or simply:

markdown

Thanks [charlie](https://github.com/charlie)!

对于之前有过贡献的贡献者，可选择性感谢，但不要提及“首次贡献”：

markdown

感谢 [charlie](https://github.com/charlie) 的贡献！

或简单表述：

markdown

感谢 [charlie](https://github.com/charlie)！

Multiple Contributors

多位贡献者

When multiple people contributed to a feature:

markdown

Thanks [alice](https://github.com/alice) and [bob](https://github.com/bob) for your contributions!

当多位贡献者参与同一功能时：

markdown

感谢 [alice](https://github.com/alice) 和 [bob](https://github.com/bob) 的贡献！

Special Notations

特殊标记

Notes to Distributors

面向分发者的说明

Use blockquotes for notes to distributors or package maintainers:

markdown

> Note to distributors: you can disable self-update by building cargo-nextest with `--no-default-features`.

使用块引用标记面向分发者或包维护者的说明：

markdown

> 面向分发者的说明：你可以通过`--no-default-features`编译cargo-nextest来禁用自我更新功能。

Upcoming Changes

即将到来的变更

For warning about future behavior changes:

markdown

undefined

用于警告未来的行为变更：

markdown

undefined

Upcoming behavior changes

即将到来的行为变更

If no tests are run, nextest will start exiting with the advisory code 4 in versions released after 2024-11-18. See discussion #1646 for more.

undefined

若未运行任何测试，nextest将在2024-11-18之后发布的版本中以警告代码4退出。更多信息请查看讨论#1646。

undefined

Experimental Features

实验性功能

Clearly mark experimental features:

markdown

- Experimental support for [feature name](link). Please try them out, and provide feedback in the [tracking issue](link)!

明确标记实验性功能：

markdown

- 新增对[功能名称](链接)的实验性支持。欢迎试用，并在[追踪Issue](链接)中提供反馈！

Breaking Changes

破坏性变更

If a release contains breaking changes, consider adding a note at the top:

markdown

This is a major release with several new features. It's gone through a period of beta testing, but if you run into issues please [file a bug]!

若版本包含破坏性变更，可考虑在顶部添加说明：

markdown

这是一个包含多项新功能的重大版本。该版本已通过Beta测试，若遇到问题请[提交Bug]！

Formatting Conventions

格式约定

Code and Commands

代码与命令

Use backticks for inline code:
```
`cargo nextest run`
```
Use triple backticks for code blocks with language specification:
```
```toml
```
,
```
```bash
```

使用反引号包裹行内代码：
```
`cargo nextest run`
```
使用三重反引号包裹代码块并指定语言：
```
```toml
```
、
```
```bash
```

Configuration Examples

配置示例

When showing configuration:

markdown

For example, to time out after 120 seconds:

  ```toml
  slow-timeout = { period = "60s", terminate-after = 2 }


Note the indentation for the code block within a bullet point.

展示配置时：

markdown

例如，要设置120秒后超时：

  ```toml
  slow-timeout = { period = "60s", terminate-after = 2 }


注意项目符号内代码块的缩进。

Environment Variables

环境变量

Use all caps with backticks:
```
`NEXTEST_RETRIES`
```
Use the format
```
`NAME=value`
```
when showing how to set them

使用全大写字母加反引号：
```
`NEXTEST_RETRIES`
```
展示设置方式时使用
```
`NAME=value`
```
格式

Version References

版本引用

Cargo versions: "Cargo 1.87"
Rust versions: "Rust 1.64"
Nextest versions: "nextest 0.9.100" or "version 0.9.100"

Cargo版本：“Cargo 1.87”
Rust版本：“Rust 1.64”
Nextest版本：“nextest 0.9.100”或“version 0.9.100”

Dependency Updates

依赖更新

List major dependency updates or security updates separately:

markdown

- Update rust-openssl for [CVE-2025-24898](https://nvd.nist.gov/vuln/detail/CVE-2025-24898).

单独列出主要依赖更新或安全更新：

markdown

- 针对[CVE-2025-24898](https://nvd.nist.gov/vuln/detail/CVE-2025-24898)更新rust-openssl。

Examples of Well-Formed Entries

格式规范的条目示例

Simple Feature Addition

简单功能新增

markdown

undefined

markdown

undefined

Added

A new
```
--hide-progress-bar
```
option (environment variable
```
NEXTEST_HIDE_PROGRESS_BAR
```
) forces the progress bar to be hidden. Thanks Remo Senekowitsch for your first contribution!

undefined

新增
```
--hide-progress-bar
```
选项（对应环境变量
```
NEXTEST_HIDE_PROGRESS_BAR
```
），可强制隐藏进度条。感谢 Remo Senekowitsch 提交首次贡献！

undefined

Complex Feature with Documentation

带文档的复杂功能

markdown

undefined

markdown

undefined

Added

Nextest now supports assigning test priorities via configuration.

undefined

Nextest现在支持通过配置分配测试优先级。

undefined

Bug Fix with Issue Link

带Issue链接的Bug修复

markdown

undefined

markdown

undefined

Fixed

Fixed an occasional hang on Linux with libtest JSON output. For more details, see #2316.

undefined

修复了Linux下使用libtest JSON输出时偶尔出现的挂起问题。更多细节请查看#2316。

undefined

Breaking Change

破坏性变更

markdown

undefined

markdown

undefined

Changed

If nextest is unable to parse
```
--target
```
(and in particular, a custom target), it now fails rather than printing a warning and assuming the host platform. This is being treated as a bugfix because the previous behavior was incorrect.

undefined

若nextest无法解析
```
--target
```
参数（尤其是自定义目标），现在会直接失败，而非打印警告并假设使用主机平台。此变更被视为Bug修复，因为之前的行为存在错误。

undefined

Determining What Changed

确定变更内容

To generate a changelog entry:

Get the commit list:
```
git log <previous-tag>..main --oneline
```
Review each commit to determine if it's user-visible
Group related commits together (e.g., multiple USDT commits into one feature)

Check for first-time contributors:

git log --all --author="Name" --oneline | wc -l

Get PR author GitHub username:

gh pr view <number> --json author --jq '.author.login'

Examine key commits for context:
```
git show <commit> --stat
```

Filter out:

Documentation site updates (unless they document new features)
CI configuration changes
Internal refactoring without user impact
Most dependency updates (group them together)

要生成更新日志条目：

获取提交列表：
```
git log <previous-tag>..main --oneline
```
审核每个提交，判断是否为用户可见的变更
将相关提交分组（例如，多个USDT相关提交合并为一个功能条目）

检查是否为首次贡献者：

git log --all --author="Name" --oneline | wc -l

获取PR作者的GitHub用户名：

gh pr view <number> --json author --jq '.author.login'

查看关键提交的上下文：
```
git show <commit> --stat
```

需过滤掉以下内容：

文档站点更新（除非是为新功能编写的文档）
CI配置变更
无用户影响的内部重构
大多数依赖更新（可合并分组）