// Changelog style guide for writing RELEASE.md files. Use when creating or reviewing RELEASE.md, writing changelog entries, or preparing a PR that needs a changelog.
| 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 a changelog. |
This guide describes the style for writing RELEASE.md files for hegel-go. The style is modeled on the Hypothesis changelog.
Every entry should open with a sentence that signals the scope and nature of the change:
"This patch ...""This release ...""Internal refactoring." or "Clean up some internal code."The opening verb should tell the reader what kind of change this is:
| Change type | Opening pattern |
|---|---|
| Bug fix | "This patch fixes ..." or "Fix ..." |
| New feature | "This release adds ..." |
| Improvement | "This patch improves ..." or "This release makes ... more ..." |
| Deprecation | "This release deprecates ..." |
| Breaking change | "This release changes ..." (then explain migration) |
| Performance | "This patch improves the performance of ..." or "Optimize ..." |
| Internal-only | "Internal refactoring." / "Refactor some internals." / "Clean up some internal code." |
Bad: "Refactored the socket handling code to use a shared connection pool."
Good: "This release 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-go/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 `Slices` 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 minor (new feature):
RELEASE_TYPE: minor
This release 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 `SuppressHealthCheck` setting.
Good major (breaking change):
RELEASE_TYPE: major
This release changes the signature of `RunHegelTest` to accept a `*testing.T` instead of a `testing.TB`:
\```go
// before
func RunHegelTest(t testing.TB, body func()) {}
// after
func RunHegelTest(t *testing.T, body func()) {}
\```
This will require updating your test function signatures, but should be strictly more expressive.
Go concurrency patterns and pitfalls for this codebase. Use when writing or reviewing code that involves goroutines, channels, mutexes, shared state, subprocess management, or anything that runs concurrently. Also use proactively when writing new code — ask yourself: can this be called from multiple goroutines? Is this resource process-global?
How to approach code coverage in this project. Use when coverage CI fails, when writing tests for new code, when deciding whether to add // coverage-ignore, or when you need to make untestable code testable. Also use proactively when writing new code to ensure it will be coverable.
Review your own changes before creating a pull request. Use this before running create-pr, or whenever you want to check that your changes are clean, correct, and well-tested. Trigger when: about to create a PR, finished a chunk of work, or asked to review changes.