Changelog and Versioning Skill

This skill transforms technical git commits into polished, user-facing changelogs that your customers and users will understand and appreciate.

When to Use

• Preparing release notes for a new version
• Documenting changes for the website
• Creating or editing documentation pages
• Ensuring consistent writing style across content

What It Does

1. Scans Git History: Analyzes commits from a specific time period or between versions.
2. Categorizes Changes: Groups commits into logical categories (features, improvements, bug fixes, breaking changes).
3. Translates Technical → User-Friendly: Converts developer commits into customer language.
4. Formats Professionally: Creates clean, structured changelog entries following Kubb conventions.
5. Filters Noise: Excludes internal commits (refactor, test, etc.).
6. Follows Best Practices: Applies changelog guidelines and your brand voice.

Kubb uses Changesets for version management and maintains a comprehensive changelog in docs/changelog.md.

Changeset Workflow

Creating a Changeset

For every PR with code changes, create a changeset:

pnpm changeset

Interactive prompts:

1. Select which packages are affected
2. Choose version bump type (major / minor / patch)
3. Write a concise summary of the changes

Version Bump Types

Type	Description
Major (breaking)	Changes that break existing functionality
Minor (feature)	New features that don't break existing functionality
Patch (fix)	Bug fixes and minor improvements

Changelog Format

The changelog follows a specific structure in docs/changelog.md.

• Use ## for version headings (not #).
• Use ### for change type sections with emoji prefixes.
• Use #### for individual plugin names with links.

Change type:

Category	Description
✨ Features	New functionality and enhancements
🐛 Bug Fixes	Bug fixes and corrections
🚀 Breaking Changes	Changes that may require code updates
📦 Dependencies	Package updates and dependency changes

Example:

2.5.0

✨ Features

plugin-ts

Added support for generating union types with the new unionType option.

::: code-group

// Generated separate types
export type PetDog = { type: 'dog'; bark: string }
export type PetCat = { type: 'cat'; meow: string }

export type Pet = PetDog | PetCat

:::

Changelog Style

Documenting Bug Fixes

When fixing bugs that affect user-facing behavior:

1. Update relevant documentation

• Fix incorrect examples
• Clarify ambiguous descriptions
• Update troubleshooting guide if applicable

2. Add to changelog (via pnpm changeset)

• Explain what was broken
• Show correct usage
• Link to relevant docs

3. Consider migration notes

• If fix changes expected behavior
• Add to migration guide with before/after examples

Example:

Fixed incorrect enum type output

Issue: enumType: 'asConst' generated invalid TypeScript

Fixed: Now correctly generates:

const petType = {
  Dog: 'dog',
  Cat: 'cat',
} as const

Related Skills

| Skill | Use For | | ---------------------------------------------------------- | ------------------- | ------------------------------------------ | | ../documentation/SKILL.md | Documentation style | Adding documentation for changelog entries |

Checklist

• All code changes have corresponding documentation updates
• Frontmatter is complete and correct
• Changeset updated via pnpm changeset (for code changes)
• Changelog added or updated in docs/changelog.md

Resources

• Changesets Documentation: https://github.com/changesets/changesets
• VitePress Markdown Extensions: https://vitepress.dev/guide/markdown