// Changelog style guide for writing RELEASE.md files. Use when creating or reviewing RELEASE.md, writing changelog entries, or preparing a PR that needs release notes.
| name | changelog |
| description | Changelog style guide for writing RELEASE.md files. Use when creating or reviewing RELEASE.md, writing changelog entries, or preparing a PR that needs release notes. |
This guide describes the style for writing RELEASE.md files for hegel-rust. The style is modeled on the Hypothesis changelog.
RELEASE_TYPEhegel-rust is currently zerover (0.x.y), so the usual semver mapping does not apply. While we are pre-1.0:
patch — Bug fixes, internal changes, and new features / non-breaking API additions. The default choice.minor — Breaking changes only. Any change that requires users to update their code (renamed/removed APIs, changed signatures, behavior changes that could break downstream tests) is a minor bump.major — Not used while we are zerover. Reserve for the eventual 1.0 and beyond.If you find yourself reaching for minor because the change feels "big," check whether it actually breaks any caller. A large new feature that adds API surface without removing or changing existing behavior is still a patch.
Every entry should open with a sentence that signals the scope and nature of the change:
"This patch ...""This release ..." and explain migration"Internal refactoring." or "Clean up some internal code."The opening verb should tell the reader what kind of change this is:
| Change type | RELEASE_TYPE | Opening pattern |
|---|---|---|
| Bug fix | patch | "This patch fixes ..." or "Fix ..." |
| New feature | patch | "This patch adds ..." |
| Improvement | patch | "This patch improves ..." |
| Performance | patch | "This patch improves the performance of ..." or "Optimize ..." |
| Deprecation | minor | "This release deprecates ..." |
| Breaking change | minor | "This release changes ..." (then explain migration) |
| Internal-only | patch | "Internal refactoring." / "Refactor some internals." / "Clean up some internal code." |
Bad: "Refactored the socket handling code to use a shared connection pool."
Good: "This patch changes the way the client manages the server to run a single persistent process for the whole test run. This should improve the performance of running many hegel tests."
For bug fixes, describe the bug (what went wrong from the user's perspective), not just "fixed a bug":
Bad: "Fix bug in server crash detection."
Good: "Fix server crash detection. The client now properly detects when the hegel server process exits unexpectedly, instead of hanging indefinitely."
"Refactor some internals.")Don't pad entries. If a change can be described in one sentence, use one sentence.
Include fenced code blocks for:
Don't include code blocks for bug fixes or internal changes.
([#123](https://github.com/hegeldev/hegel-rust/issues/123))"This should improve performance", "We expect this to...", "In some cases this may...""various improvements" — be specific about what changedGood patch (bug fix):
RELEASE_TYPE: patch
This patch fixes `generators::hashsets` generating duplicate elements in rare cases when the element generator had a very small output space.
Good patch (internal):
RELEASE_TYPE: patch
Internal refactoring of the protocol handling code.
Good patch (new feature):
RELEASE_TYPE: patch
This patch adds support for `HealthCheck`. A health check is a proactive error raised by Hegel when we detect your test is likely to have degraded testing power or performance. For example, `FilterTooMuch` is raised when too many test cases are filtered out by the rejection sampling of `.filter()` or `assume()`.
Health checks can be suppressed with the new `suppress_health_check` setting.
Good minor (breaking change):
RELEASE_TYPE: minor
This release changes `self` in `#[invariant]` from an immutable reference to a mutable reference:
\```rust
# before
fn my_invariant(&self, ...) {}
# after
fn my_invariant(&mut self, ...) {}
\```
This will require updating your invariant signatures, but should be strictly more expressive.
How to add hegel-rust support for a third-party Rust crate. Use when the user asks to 'add support for <crate>', 'add a <crate> integration', 'add generators for <crate>', or similar. Orchestrates implementing a generator and DefaultGenerator impl for every public type the crate exposes.
How to add a DefaultGenerator impl for a type so gs::default::<T>() works. Use when the user asks to wire up default() for a type, add a default generator, or make a type usable with #[derive(Generate)]. Pair after the new-generator skill when adding a fresh generator, or use standalone when the underlying generator already exists or can be composed from existing generators.
How to add a new generator to hegel-rust. Use when the user asks to implement, add, or write a generator for a type — e.g. 'add a generator for Url', 'implement a UUID generator', 'write a generator for jiff::civil::Date'. Covers the generator struct, builder methods, Generate trait impl, schema asserts, mod.rs wiring, rustdoc, and the required test set. Pair with the new-default-generator skill to also wire up gs::default::<T>().