Claude Code Plugins

Community-maintained marketplace

Feedback

prepare-changelog

@nextest-rs/nextest
2.7k
0

Guidelines for preparing changelog entries for nextest releases following Keep a Changelog format

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name prepare-changelog
description Guidelines for preparing changelog entries for nextest releases following Keep a Changelog format

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

  1. Added - New features
  2. Changed - Changes to existing functionality
  3. Fixed - Bug fixes
  4. Deprecated - Soon-to-be removed features
  5. Removed - Removed features
  6. Security - Security-related changes
  7. Known issues - Known problems with this release
  8. Miscellaneous - Other notable changes that don't fit elsewhere
  9. 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

  1. Be concise but descriptive: Each bullet should clearly explain what changed and why it matters
  2. Use present tense: "Nextest now supports..." not "Nextest now supported..."
  3. Link to documentation: When introducing features, link to relevant docs with the full URL path
  4. 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](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):

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:

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

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

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

Or simply:

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

Multiple Contributors

When multiple people contributed to a feature:

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:

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

Experimental Features

Clearly mark experimental features:

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

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:

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

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

  1. Get the commit list: git log <previous-tag>..main --oneline
  2. Review each commit to determine if it's user-visible
  3. Group related commits together (e.g., multiple USDT commits into one feature)
  4. Check for first-time contributors: git log --all --author="Name" --oneline | wc -l
  5. Get PR author GitHub username: gh pr view <number> --json author --jq '.author.login'
  6. 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)