Skip to content

changelog-format.md

Latest commit

 

History

History
210 lines (155 loc) · 9.19 KB

changelog-format.md

File metadata and controls

210 lines (155 loc) · 9.19 KB
Raw

CHANGELOG Entry Format

Reference for writing and reviewing CHANGELOG entries in the hoist-react library CHANGELOG.md.

Library vs. Application changelogs: This guide applies to hoist-react and other Hoist library packages. Hoist application changelogs have different formatting requirements — see the Application Changelogs section at the end of this document.

Entry Structure

Every major version entry should use this structure. Minor/patch releases use whichever sections apply.

## {VERSION} - {YYYY-MM-DD}

### 💥 Breaking Changes (upgrade difficulty: {RATING})

See [`docs/upgrade-notes/v{NN}-upgrade-notes.md`](docs/upgrade-notes/v{NN}-upgrade-notes.md) for
detailed, step-by-step upgrade instructions with before/after code examples.

* {Required change 1}
* {Required change 2}
    * {Sub-detail if needed}
* ...

### 🎁 New Features

* {Feature description}

### 🐞 Bug Fixes

* {Fix description}

### ⚙️ Technical

* {Internal change description}

### ⚙️ Typescript API Adjustments

* {Type-level change description}

### 🤖 AI Docs + Tooling

* {AI docs/tooling change description}

### ✨ Styles

* {CSS/SCSS change description}

### 📚 Libraries

* {Library} `{old} → {new}`

Section Headers

Use these emoji-prefixed headers consistently:

Section Header When to Include
Breaking Changes ### 💥 Breaking Changes Required app changes exist
New Features ### 🎁 New Features New capabilities added
Bug Fixes ### 🐞 Bug Fixes Bugs fixed
Technical ### ⚙️ Technical Internal changes worth noting
TS API Adjustments ### ⚙️ Typescript API Adjustments Type-level changes (signatures, generics, exports)
AI Docs + Tooling ### 🤖 AI Docs + Tooling AI assistant docs, MCP server, CLI tools
Styles ### ✨ Styles CSS/SCSS changes, new variables, class renames
Libraries ### 📚 Libraries Major dependency version bumps

Note: TS API Adjustments and Technical share the ⚙️ emoji but are distinct sections. TS API Adjustments covers type signature changes that may affect app compilation but not runtime behavior. Technical covers internal implementation changes worth noting.

Voice and Tense

  • Past tense, action-driven for descriptions: "Enhanced", "Fixed", "Added", "Improved", "Removed", "Refactored"
  • Imperative for developer instructions: "Update", "Adjust", "Remove", "Migrate"
  • Avoid starting bullets with "New" (prefer "Added"), "Support for" (prefer "Added support for"), or present tense verbs like "Fix", "Allow", "Enable"

Examples

Good:

* Enhanced `GridModel` column state management to support partial updates.
* Added support for `warning` and `info` severity in `Field.rules`.
* Fixed regression with `Store.revert()` on stores with summary records.

Bad:

* New support for warning severity in rules    (use "Added", not "New support for")
* Fix to regression in Store.revert            (use "Fixed regression", not "Fix to")
* Allow improved editing of columns            (use "Enhanced" or "Added", not "Allow")

Breaking Changes Section

Every major version with breaking changes MUST include all of the following. Do not skip or reorder these requirements:

  1. Difficulty rating in the header — append (upgrade difficulty: {RATING}) to the section header. See Difficulty Ratings below for the rating scale.
  2. Upgrade notes link as a standalone sentence — immediately after the header (before any bullets), include a sentence linking to the upgrade notes file. This is not a bullet point — it is a standalone paragraph. Use this exact format: 
    See [`docs/upgrade-notes/v{NN}-upgrade-notes.md`](docs/upgrade-notes/v{NN}-upgrade-notes.md) for
detailed, step-by-step upgrade instructions with before/after code examples.
  3. List every required app-level change as a separate bullet
  4. Be specific — name exact classes, methods, and config keys
  5. Link to relevant framework upgrade guides (e.g. Blueprint, AG Grid) when applicable

Each bullet should be concise (1-2 lines). The upgrade notes file handles expanded detail with before/after code examples.

Grouping by Topic (large releases only)

When a major version carries an unusually large set of breaking changes - roughly eight or more bullets, spanning several unrelated areas - group them under #### topic sub-headers instead of presenting one flat list. This is a special case for big releases; ordinary versions keep the flat list.

  • Add a short lead-in paragraph after the ### 💥 header (following the upgrade notes link) telling readers that the changes are grouped and which groups affect every app.
  • Name groups for the area an app developer would search for: React 19, Build Tooling, Data - Cube, Data - Store and Records, Grid - Column Chooser and Column State.
  • Order groups by how broadly they apply - framework-wide and tooling changes first, then package-specific ones.
  • Keep the difficulty rating on the ### header, summarizing the release as a whole. Do not rate individual groups.
  • Group only Breaking Changes. Other sections (New Features, Bug Fixes) stay flat, since readers scan them rather than work through them.

Deprecations and Removals

Keep them together so a reader can see every scheduled removal in one place:

  • Removals of previously deprecated APIs go in a Scheduled Removals sub-list under Breaking Changes, one sub-bullet per removal, naming the version that deprecated it and the replacement.
  • New deprecations that keep the API working go under Technical, and say what replaces the deprecated API. Put one under Breaking Changes only when it accompanies the change that replaces it and apps must act now.

Difficulty Ratings

When upgrade notes exist for a major version, include a difficulty rating:

### 💥 Breaking Changes (upgrade difficulty: 🎉 TRIVIAL)
### 💥 Breaking Changes (upgrade difficulty: 🟢 LOW - {brief description})
### 💥 Breaking Changes (upgrade difficulty: 🟠 MEDIUM - {brief description})
### 💥 Breaking Changes (upgrade difficulty: 🔴 HIGH - {brief description})

Libraries Section

List major dependency version changes with backtick-wrapped versions:

### 📚 Libraries

* @blueprintjs/core `5.10 → 6.3`
* react-grid-layout `1.5 → 2.1`
* typescript `5.8 → 5.9`

Use abbreviated versions where the minor/patch isn't significant (e.g. 6.3 not 6.3.1).

General Guidelines

  • Positive tone: Favor words like "Enhanced", "Improved", "Streamlined" where accurate. Concisely note why a change is an improvement when not obvious from context (e.g. "Improved shutdown handling — ensures full cleanup if the component unmounts unexpectedly"). Accuracy always takes precedence — bug fixes should be reported clearly as such.
  • Conciseness: This is a changelog, not a guide. One bullet = one change, 1-3 lines max. Upgrade notes provide granular detail when needed; keep changelog entries brief and scannable.
  • Specificity: Name classes, methods, and config keys in backticks.
  • Completeness: Changes that modify behavior, APIs, or configuration in ways developers need to know about should be accounted for. Trivial changes (formatting, internal refactors with no behavioral impact, tooling updates) do not need to be included.
  • No duplication: Don't repeat the same change across sections. Pick the most relevant section.
  • Issue/PR links: Don't add GitHub issue or PR links (e.g. [#1234]) to entries by default. Include one only when explicitly requested, or when it points to extensive context that genuinely doesn't fit the changelog's scope. Issue/PR references normally belong in the commit message and PR description, not the changelog.
  • Relevance test: Include a fact only if a developer or agent upgrading an app needs it to adopt the release well. Exact counts, timings, token figures, and enumerations of CSS variables or similar fine-grained additions fail that test; acknowledge such additions in general terms.
  • Library names: In prose, name third-party libraries by their product name (AG Grid, Blueprint, MobX). Package names and import paths keep their own spelling inside code spans.
  • Punctuation: End each bullet with a period.
  • Line wrapping: Hard-wrap list item text at 100 characters. Use two-space indentation for continuation lines. This keeps the raw Markdown readable in editors and diffs.

Application Changelogs

Hoist application changelogs (e.g. in app repos that depend on @xh/hoist) follow different formatting rules than the library changelog described above. Application changelogs are parsed at runtime by a Hoist release notes feature that displays them within the app UI.

Do NOT hard-wrap list items in application changelogs. Each bullet point must be a single unwrapped line — the release notes parser treats line breaks within a list item as separate entries. Let the viewing tool handle display wrapping.

All other conventions (section headers, voice/tense, backtick-wrapped specificity) apply to both library and application changelogs.