What inputs are required?

Release version + date (or 'unreleased'), range from_ref..to_ref, target audience, and what to include/exclude. If unknown, prompt for last release tag and target branch/tag.

How are changes categorized?

Changes are grouped into Highlights, Breaking changes, Features, Fixes, Performance, Security, Deprecations, Docs, Dependencies, and Infra/ops, using first-parent history and merged PR titles when available.

What outputs are generated?

Release notes in Markdown suitable for GitHub Release, plus a short Risk/notes section detailing migrations, config changes, and rollback concerns. References to PRs/issues are included only when stable in the repository.

release-notes

Scanned

npx machina-cli add skill jmerta/codex-skills/release-notes --openclaw

Files (1)

SKILL.md

2.6 KB

Release notes

Goal

Produce accurate, scannable release notes (Markdown) for a specific release range.

Inputs to ask for (if missing)

Release version + date (or "unreleased").
Range to summarize: from_ref..to_ref (tags/SHAs/branches). If unknown, ask: "last release tag?" and "target branch/tag?"
Target audience: end users, developers, internal ops, or all.
What to include/exclude: internal refactors, dependency bumps, infra-only changes.

Workflow (checklist)

Determine the release range
- Prefer tags: pick the previous tag and the new tag/HEAD.
- If no tags: use the last release branch point or a date-based window.
- Commands to gather candidates:
  - git tag --sort=-creatordate | Select-Object -First 20
  - git log --first-parent --oneline <from_ref>..<to_ref>
  - If GitHub CLI is available: list merged PRs for the range and use titles for grouping.
Collect and categorize changes
- Start from merge commits (first-parent) to avoid noise.
- Categorize into: Highlights, Breaking changes, Features, Fixes, Performance, Security, Deprecations, Docs, Dependencies, Infra/ops.
- Flag anything requiring action: config changes, env vars, DB migrations, API contract changes.
Identify breaking changes and upgrade steps
- Look for: renamed/removed endpoints, changed request/response fields, changed config keys, Java/Kotlin/Node version bumps, DB schema changes.
- Add explicit "Upgrade" and "Rollback" notes when impact is non-trivial.
Write release notes using the template
- Use short bullets, active voice, and user-facing wording.
- Prefer "what changed" + "why it matters" over implementation details.
- Include PR/issue references only if they are stable in your repo hosting.
- Use references/release-notes-template.md to keep structure consistent.
Sanity check for omissions and accuracy
- Diff the range: git diff --stat <from_ref>..<to_ref>
- Scan for config/migrations: rg -n \"ENV|config|migration|Flyway|Liquibase\" -S
- Ensure breaking changes are called out and have upgrade steps.

Deliverable

Provide:

Release notes Markdown (ready to paste into a GitHub Release / changelog).
A short "Risk/notes" section listing any required migrations, config changes, or rollback concerns.

Source

git clone https://github.com/jmerta/codex-skills/blob/main/release-notes/SKILL.mdView on GitHub

Overview

Automatically draft accurate, scannable release notes and changelogs by summarizing commits and merged PRs between two refs. It groups changes into categories like Highlights, Breaking changes, Features, Fixes, Migrations, Docs, and more, flagging actions needed such as config changes or migrations. Outputs follow a consistent Markdown template suitable for GitHub Releases and changelogs.

How This Skill Works

The skill first determines the release range (preferring tags, then last release point or a date window). It then collects changes by walking the first-parent history and, when available, using merged PR titles for logical grouping. It identifies breaking changes and upgrade steps, and writes notes using the published template (references/release-notes-template.md) to produce Markdown release notes plus a risk/notes section.

When to Use It

Preparing a GitHub Release or changelog for a new version.
Drafting notes for a range of commits between two refs (tags, SHAs, or branches).
Highlighting breaking changes, migrations, and upgrade steps for end users or developers.
Generating notes with a structured template for consistency across releases.
When you want a focused, scan-friendly release note with PR references only if stable.

Quick Start

Step 1: Provide release range (from_ref..to_ref) and version/date (or 'unreleased').
Step 2: Run the release-notes tool to collect, categorize, and draft Markdown notes.
Step 3: Review, adjust as needed, then paste into GitHub Release and add risk notes.

Best Practices

Ask for release range and version/date up front to avoid gaps.
Start from merge commits (first-parent) to minimize noise.
Categorize changes into clear sections: Highlights, Breaking changes, Features, Fixes, Migrations, Docs, etc.
Flag config changes, environment variables, and database migrations with explicit upgrade/rollback guidance.
Review notes against the git diff and migration keywords (ENV, migration, migration scripts) for completeness.

Example Use Cases

Release notes for v2.3.0 from v2.2.5..HEAD with breaking API changes and DB migrations.
Unreleased draft for upcoming release, including new features and fixes.
Changelog focusing on dependency bumps and infra changes.
Notes highlighting security fixes and documentation updates.
Internal-ops release notes detailing deployment script updates and CI changes.

Frequently Asked Questions

Add this skill to your agents