changelog-maintenance_skill

Overview

This skill maintains a clear, user-focused changelog and release notes for software projects. It enforces Keep a Changelog structure, semantic versioning rules, and produces developer and user-facing artifacts. The output set includes CHANGELOG.md, RELEASES.md, and a docs/migration/ folder with migration guides.

How this skill works

It inspects commits, release content, and feature/bug-tracking inputs to generate an ordered, dated changelog with categorized entries (Added, Changed, Fixed, Deprecated, Removed, Security). It maps changes to semantic version bumps (MAJOR.MINOR.PATCH), creates user-friendly release notes, and writes migration guides for breaking changes. It validates dates in ISO 8601 format and ensures latest versions appear first.

When to use it

• Before a release to compile all notable changes
• After major features or bug fixes to update the log incrementally
• When preparing release notes for end users or stakeholders
• When planning a version bump and deciding MAJOR/MINOR/PATCH
• When removing or deprecating APIs and needing a migration guide

Best practices

• Follow Keep a Changelog format and keep categories consistent (Added, Changed, Fixed, Deprecated, Removed, Security).
• Use semantic versioning rules: MAJOR for breaking changes, MINOR for backward-compatible features, PATCH for bug fixes and security patches.
• Write concrete, user-focused entries (what changed, why, and migration steps) — avoid vague phrases like “bug fixes”.
• Include ISO 8601 dates (YYYY-MM-DD) and always list releases newest-first (reverse chronological).
• Provide a concise migration guide for any breaking change with code examples and a deprecation timeline.

Example use cases

• Generate CHANGELOG.md from release notes and PR summaries before publishing v1.2.0
• Create RELEASES.md with friendly bullet points and upgrade instructions for non-technical users
• Draft docs/migration/v1-to-v2.md describing API auth changes and response-format migrations
• Automate semantic version bump decisions based on tagged changes and breaking-change markers
• Produce security sections listing dependency updates and CVE fixes in each release