prepare-changelog

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

[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:

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

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

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
Examples: GHSA-xxxx , CVE-xxxx

Contributor Attribution

First-time Contributors

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

Thanks 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:

New feature that does something. Thanks alice for your first contribution!

Added

Feature A
Feature B

Thanks bob for your first contribution!

Returning Contributors

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

Thanks charlie for your contribution!

Or simply:

Thanks charlie!

Multiple Contributors

When multiple people contributed to a feature:

Thanks alice and bob for your contributions!

Special Notations

Notes to Distributors

Use blockquotes for notes to distributors or package maintainers:

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

Upcoming Changes

For warning about future behavior changes:

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.

Experimental Features

Clearly mark experimental features:

Experimental support for feature name. Please try them out, and provide feedback in the tracking issue!

Breaking Changes

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

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:

For example, to time out after 120 seconds:

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

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

### Added

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

Bug Fix with Issue Link

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

### 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 &#x3C;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 &#x3C;number> --json author --jq '.author.login'

- Examine key commits for context: git show &#x3C;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)