balakit / rules

---
description: Maintain CHANGELOG.md for significant changes; grouped by type (Features, Fixes, Changes); source for GitHub release notes
alwaysApply: true
---

# Changelog maintenance

## When to update

Update `CHANGELOG.md` (at project root) whenever you or the user:

- Add a **new feature**
- Ship a **significant fix** (bug fix that affects behavior or correctness)
- Make a **notable change** (refactor, config, dependency, or UX change worth documenting)
- Remove or deprecate something user-facing

Do **not** add trivial edits (typos, comment-only, formatting-only) unless the user asks.

## Format (grouped by type)

- **Unreleased at top.** The first section is `## [Unreleased]` for changes not yet in a release.
- **Released versions below.** Each release has a section `## [vX.Y.Z]` or `## [X.Y.Z]` (e.g. `## [v0.0.1-beta.7]`, `## [1.0.0]`). Use the exact version string that will be tagged (with or without leading `v`).
- **Newest release first** under Unreleased. When you cut a release, the previous `[Unreleased]` content can be moved under a new `## [vX.Y.Z]` section.
- **Group by type.** Within each version section, organize entries under three subsections: `### Features`, `### Fixes`, `### Changes`.
- **No type prefix.** Items do not need `**Feature:**`, `**Fix:**`, or `**Change:**` prefixes since they are grouped by section.
- One line per item; keep text concise.

Structure:

```markdown
# Changelog

## [Unreleased]

### Features
- Short description of new feature.
- Another feature.

### Fixes
- Bug fix description.
- Another fix.

### Changes
- Refactor or UX change description.

## [v0.0.1-beta.7]

### Features
- Something shipped in this version.

### Changes
- Another change.

## [v0.0.1-beta.6]
- ...
```

## Releases and GitHub

If the project uses a tag-triggered release workflow, it typically looks in `CHANGELOG.md` for a section whose heading matches the pushed tag (e.g. `## [v1.2.3]` or `## [1.2.3]`) and uses that section as the release notes body. Add the version section before tagging so the release notes are populated; if it's missing, the release should still succeed with a default body.

## If the file is missing

If `CHANGELOG.md` does not exist, create it with a title, an `## [Unreleased]` section, and add the relevant entry/entries.