Skip to content

docs(release): omit empty sections in release notes guidance #278

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
leggetter merged 1 commit into from
Mar 27, 2026
Merged

docs(release): omit empty sections in release notes guidance #278

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions skills/hookdeck-cli-release/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,11 +136,13 @@ The user may suggest a tag (e.g. `v2.0.1`). **Always sanity-check it** against w

Use **[references/release-notes-template.md](references/release-notes-template.md)** as a starting skeleton.

**Sections:** Include only headings that have real content — **omit** empty sections (e.g. do not add “Breaking changes” with “None”).

**Patterns observed in this repo:**

- **Large GA (e.g. v2.0.0):** `Summary` → `Breaking changes / migration` → `New features` (subsections per area) → `Improvements / behavior changes` → optional `Internal`.
- **Large GA (e.g. v2.0.0):** `Summary`, then as needed: `Breaking changes / migration`, `New features` (subsections per area), `Improvements / behavior changes`, `Internal` — skip any block with nothing to say.
- **Feature release (e.g. v1.9.0):** `## Features` with detailed bullets + **Full Changelog** compare link.
- **Patch (e.g. v1.9.1):** `## Fixes`, `## Updates`, PR links with authors + **Full Changelog**.
- **Patch (e.g. v1.9.1):** `## Fixes`, `## Updates`, PR links with authors + **Full Changelog** — omit unused sections.

Always include a **Full Changelog** line:

Expand Down
12 changes: 7 additions & 5 deletions skills/hookdeck-cli-release/references/release-notes-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,29 +2,31 @@

Copy and fill in for the GitHub release description (e.g. write into the temp file used with `gh release create --notes-file`). Adjust heading levels (`##` vs `###`) to match recent GA style (v2.0.0 used `###` subsections) or smaller patch style (v1.9.x used `##`).

**Do not include a section if there is nothing to say** — omit the heading entirely (do not add “Breaking changes” with “None”, empty “Fixes”, etc.). Typical releases only need a subset of the sections below.

## Summary

<!-- 2–4 sentences: who benefits, scope since previous tag (e.g. since `v1.9.1`). -->

## Breaking changes / migration

<!-- Omit or state "None" for patch releases if accurate. For each item: what changed, why, what users must update (scripts, flags, CI). -->
<!-- Include only when users must change scripts, configs, or habits. For each item: what changed, why, what to update (scripts, flags, CI). Omit this whole section when there are no breaking changes. -->

## New features

<!-- Group by area/command. User-facing language; mention important flags. -->
<!-- Include when shipping user-visible capability. Group by area/command; mention important flags. Omit if nothing applies. -->

## Fixes

<!-- Optional: merge into "Improvements" for tiny releases. -->
<!-- Omit if no fixes, or merge into Improvements for tiny releases. -->

## Improvements / behavior changes

<!-- UX, defaults, performance, reliability visible to users. -->
<!-- UX, defaults, performance, reliability visible to users. Omit if nothing applies. -->

## Internal / reliability / infrastructure

<!-- Optional: refactors, test/CI, dependency bumps with low user-visible impact. -->
<!-- Refactors, test/CI, dependency bumps with low user-visible impact. Omit if nothing worth mentioning. -->

## Contributors (optional)

Expand Down
Loading