Changelog Format Guide

This document describes the format and conventions used in

site/src/changelog.md

Overall Structure

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

Version Header

markdown

## [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)

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

Section Style

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

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

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)

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

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.

Links and References

PR and Issue Links

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

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)

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

### Added

- Feature A
- Feature B

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

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)!

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!

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`.

Upcoming Changes

For warning about future behavior changes:

markdown

### 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](https://github.com/nextest-rs/nextest/discussions/1646) for more.

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)!

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]!

Formatting Conventions

Code and Commands

Use backticks for inline code:
```
`cargo nextest run`
```
Use triple backticks for code blocks with language specification:
```
```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.

### Environment Variables

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

### Version References

- Cargo versions: "Cargo 1.87"
- Rust versions: "Rust 1.64"
- Nextest versions: "nextest 0.9.100" or "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).

Examples of Well-Formed Entries

Simple Feature Addition

markdown

### Added

- A new `--hide-progress-bar` option (environment variable `NEXTEST_HIDE_PROGRESS_BAR`) forces the progress bar to be hidden. Thanks [Remo Senekowitsch](https://github.com/remlse) for your first contribution!

Complex Feature with Documentation

markdown

### Added

- Nextest now supports assigning [test priorities](https://nexte.st/docs/configuration/test-priorities) via configuration.

Bug Fix with Issue Link

markdown

### Fixed

- Fixed an occasional hang on Linux with [libtest JSON output](https://nexte.st/docs/machine-readable/libtest-json/). For more details, see [#2316].

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

Breaking Change

markdown

### 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.

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)

prepare-changelog

NPX Install

Tags

SKILL.md Content

Changelog Format Guide

Overall Structure

Version Header

Section Organization

Section Style

Content Guidelines

What to Include

What to Exclude

Writing Style

Examples

Links and References

PR and Issue Links

External Links

Contributor Attribution

First-time Contributors

Returning Contributors

Multiple Contributors

Special Notations

Notes to Distributors

Upcoming Changes

Experimental Features

Breaking Changes

Formatting Conventions

Code and Commands

Configuration Examples

Examples of Well-Formed Entries

Simple Feature Addition

Complex Feature with Documentation

Bug Fix with Issue Link

Breaking Change

Determining What Changed