Changelog Generator

@package.json

@CHANGELOG.md

Overview

• Analyzing staged git changes to determine change types
• Calculating appropriate semantic version bumps (MAJOR.MINOR.PATCH)
• Updating the version in

  @package.json

• Generating properly formatted changelog entries in

  @CHANGELOG.md

• Ensuring consistency between version numbers and changelog entries

When to Apply

• User requests to "update changelog" or "generate changelog"
• User asks to "bump version" or "create release"
• Preparing for a new release
• Need to document changes in a standardized format
• Ensuring version numbers follow semantic versioning
• Maintaining consistent changelog formatting

• Git repository with staged changes
• Existing

  @package.json

  file with a

  version

  field
• Existing

  @CHANGELOG.md

  file following Keep a Changelog format
• Access to git commands (

  git diff

  ,

  git status

  )

Workflow

Step 1: Review All Staged Changes

1. Check git status to see what's staged:
   bash

   git status

2. Review all staged changes:
   bash

   git diff --cached

3. Analyze the changes to identify:
   • Breaking changes: API changes, removed features, incompatible changes
   • New features: Added functionality, new APIs, new components
   • Bug fixes: Fixes to existing functionality
   • Documentation: README updates, doc changes (usually don't affect version)
   • Refactoring: Code improvements without behavior changes (usually PATCH)
4. Review commit messages if available:
   bash

   git log --oneline --cached

• Breaking changes → MAJOR version bump
• New features → MINOR version bump
• Bug fixes → PATCH version bump
• Documentation only → Usually no version bump (or PATCH if significant)
• Refactoring → Usually PATCH version bump

Step 2: Determine the Appropriate Version Bump

1. Read current version from

   @package.json

   :
   bash

   # Read the version field
   cat package.json | grep '"version"'

2. Apply semantic versioning rules:
   • MAJOR (X.0.0): Increment when you make incompatible API changes
     • Breaking API changes
     • Removed features
     • Changed behavior that breaks existing code
     • Example:

       1.2.3

       →

       2.0.0

   • MINOR (0.X.0): Increment when you add functionality in a backward-compatible manner
     • New features
     • New APIs (backward compatible)
     • Deprecated features (still functional)
     • Example:

       1.2.3

       →

       1.3.0

   • PATCH (0.0.X): Increment when you make backward-compatible bug fixes
     • Bug fixes
     • Security patches
     • Performance improvements
     • Documentation updates (if versioned)
     • Example:

       1.2.3

       →

       1.2.4

3. Priority order: If multiple change types exist, use the highest:
   • MAJOR > MINOR > PATCH
   • If any breaking changes exist → MAJOR
   • Else if any new features exist → MINOR
   • Else → PATCH

Are there breaking changes?
├─ Yes → MAJOR version bump (X.0.0)
└─ No → Are there new features?
    ├─ Yes → MINOR version bump (0.X.0)
    └─ No → PATCH version bump (0.0.X)

1.2.4

Step 3: Update @package.json Version Accordingly

@package.json

1. Read the current

   @package.json

   file
2. Locate the

   "version"

   field (usually near the top)
3. Update the version number to the new version determined in Step 2
4. Preserve all formatting:
   • Keep the same indentation (spaces or tabs)
   • Maintain the same JSON structure
   • Don't modify other fields
   • Don't reorder fields
   • Keep trailing commas if they exist

// Before
{
  "name": "qa-skills",
  "version": "0.4.0",
  "private": true,
  ...
}

// After (PATCH bump)
{
  "name": "qa-skills",
  "version": "0.4.1",
  "private": true,
  ...
}

• Only update the

  version

  field
• Don't change any other content
• Maintain JSON validity
• Preserve file formatting and style

@package.json

Step 4: Update @CHANGELOG.md with a New Version Block

@CHANGELOG.md

1. Read the current

   @CHANGELOG.md

   file
2. Locate the

   ## [Unreleased]

   section (should be at the top)
3. Insert a new version block after

   ## [Unreleased]

   and before the previous version
4. Use the format:

   ## [X.Y.Z] - YYYY-MM-DD

   • X.Y.Z

     is the new version number

   • YYYY-MM-DD

     is the current date (see Step 5)

# Changelog

## [Unreleased]

## [0.4.1] - 2026-01-25

### Added
- New feature description

## [0.4.0] - 2026-01-25
...

• Place new version block between

  [Unreleased]

  and the previous release
• Use exact format:

  ## [X.Y.Z] - YYYY-MM-DD

• Maintain consistent spacing with existing entries
• Don't modify existing version entries

@CHANGELOG.md

Step 5: Add the Version and the Date

1. Get the current date in YYYY-MM-DD format
   • Use system date/time information
   • Never assume or hardcode dates
   • Format:

     YYYY-MM-DD

     (e.g.,

     2026-01-25

     )
2. Verify the version number matches Step 2 and Step 3
   • Version in changelog header must match

     @package.json

     version
   • Format:

     [X.Y.Z]

     where X, Y, Z are numbers
3. Update the version block header if needed:
   markdown

   ## [0.4.1] - 2026-01-25

• Always use

  YYYY-MM-DD

  format
• Use 4-digit year
• Use 2-digit month (01-12)
• Use 2-digit day (01-31)
• Match the format of existing changelog entries

## [1.2.4] - 2026-01-25

Step 6: Add the Changelog Data

1. Organize changes from Step 1 into appropriate sections
2. Use the standard Keep a Changelog sections:

   • ### Added

     - New features

   • ### Changed

     - Changes in existing functionality

   • ### Deprecated

     - Soon-to-be removed features

   • ### Removed

     - Removed features

   • ### Fixed

     - Bug fixes

   • ### Security

     - Security vulnerabilities
3. Format each entry:
   • Use bullet points with

     - 

     prefix
   • Start with a capital letter
   • End without a period (unless it's a full sentence)
   • Be concise and descriptive
   • Focus on user-facing changes
4. Section Guidelines:
   • Added: New features, new APIs, new components, new capabilities
   • Changed: Modified behavior, API changes (non-breaking), improvements
   • Deprecated: Features marked for removal in future versions
   • Removed: Features that were removed (usually indicates MAJOR bump)
   • Fixed: Bug fixes, corrections, patches
   • Security: Security-related fixes and improvements
5. Only include sections that have changes
6. Order sections: Added, Changed, Deprecated, Removed, Fixed, Security

## [0.4.1] - 2026-01-25

### Added
- New changelog generator skill for cursor agents
- Support for semantic versioning automation

### Fixed
- Corrected version bump logic for patch releases
- Fixed date formatting in changelog entries

### Changed
- Improved changelog entry categorization

• Write from the user's perspective
• Use present tense ("Adds feature" not "Added feature")
• Be specific but concise
• Group related changes together
• Avoid technical jargon when possible
• Focus on what changed, not how it was implemented

Step 7: One Final Review

1. Version Consistency:
   • Version in

     @package.json

     matches version in

     @CHANGELOG.md

     header
   • Version format is correct (X.Y.Z where X, Y, Z are numbers)
2. Date Format:
   • Date is in YYYY-MM-DD format
   • Date matches current date (not future or past)
   • Date format matches existing changelog entries
3. Changelog Content:
   • All staged changes are represented in the changelog
   • Changes are in the correct sections
   • No duplicate entries
   • Entries are clear and descriptive
4. Formatting:
   • Markdown formatting is correct
   • Version block is in the correct location (after

     [Unreleased]

     )
   • Proper spacing between sections
   • Consistent with existing changelog style
5. Semantic Versioning:
   • Version bump type matches change types (MAJOR/MINOR/PATCH)
   • Breaking changes → MAJOR bump
   • New features → MINOR bump
   • Bug fixes → PATCH bump
6. File Integrity:

   • @package.json

     is valid JSON

   • @CHANGELOG.md

     is valid markdown
   • No syntax errors
   • Files are properly formatted

• Fix them before completing
• Re-verify the checklist
• Ensure consistency across all files

File References

@

• @package.json

  : The root

  package.json

  file in the repository
  • Contains the

    version

    field that needs updating
  • Located at the repository root

• @CHANGELOG.md

  : The changelog file following Keep a Changelog format
  • Contains version history and change documentation
  • Located at the repository root
  • Format: Markdown with version blocks

@package.json

@CHANGELOG.md

Semantic Versioning Rules

Version Format: MAJOR.MINOR.PATCH

• MAJOR version (X.0.0): Increment when you make incompatible API changes
  • Breaking changes to public APIs
  • Removed features or functionality
  • Changed behavior that breaks existing code
  • Example:

    1.2.3

    →

    2.0.0

• MINOR version (0.X.0): Increment when you add functionality in a backward-compatible manner
  • New features added
  • New APIs (backward compatible)
  • Deprecated features (still functional)
  • Example:

    1.2.3

    →

    1.3.0

• PATCH version (0.0.X): Increment when you make backward-compatible bug fixes
  • Bug fixes
  • Security patches
  • Performance improvements
  • Documentation updates (if versioned)
  • Example:

    1.2.3

    →

    1.2.4

Pre-release and Build Metadata

• Pre-release versions:

  1.0.0-alpha.1

  ,

  1.0.0-beta.2

  ,

  1.0.0-rc.1

• Build metadata:

  1.0.0+20130313144700

Decision Priority

1. Any breaking changes → MAJOR bump
2. Any new features (without breaking changes) → MINOR bump
3. Only bug fixes → PATCH bump

Keep a Changelog Format

Structure

# Changelog

## [Unreleased]

## [X.Y.Z] - YYYY-MM-DD

### Added
- New features

### Changed
- Changes in existing functionality

### Deprecated
- Soon-to-be removed features

### Removed
- Removed features

### Fixed
- Bug fixes

### Security
- Security vulnerabilities

Section Guidelines

• Added: New features, capabilities, or functionality
• Changed: Modifications to existing functionality
• Deprecated: Features that will be removed in a future version
• Removed: Features that have been removed
• Fixed: Bug fixes and corrections
• Security: Security-related fixes and improvements

Formatting Rules

• Use

  ##

  for version headers:

  ## [X.Y.Z] - YYYY-MM-DD

• Use

  ###

  for change type sections:

  ### Added

• Use

  - 

  for bullet points
• Date format:

  YYYY-MM-DD

• Only include sections that have changes
• Order: Added, Changed, Deprecated, Removed, Fixed, Security

Best Practices

• Write from the user's perspective
• Be clear and concise
• Group related changes
• Use present tense
• Focus on what changed, not implementation details
• Keep

  [Unreleased]

  section for future changes

Quick Reference

Git Commands

# Check staging status
git status

# Review staged changes
git diff --cached

# View commit history
git log --oneline --cached

Version Bump Examples

# Current: 1.2.3

# Breaking change → 2.0.0
# New feature → 1.3.0
# Bug fix → 1.2.4

Changelog Entry Template

## [X.Y.Z] - YYYY-MM-DD

### Added
- Description of new feature

### Changed
- Description of change

### Fixed
- Description of fix

Common Patterns

Pattern: Feature Release

• Changes: New features, no breaking changes
• Version: MINOR bump (0.X.0)
• Sections:

  ### Added

  , possibly

  ### Changed

Pattern: Bug Fix Release

• Changes: Only bug fixes
• Version: PATCH bump (0.0.X)
• Sections:

  ### Fixed

Pattern: Major Release

• Changes: Breaking changes
• Version: MAJOR bump (X.0.0)
• Sections:

  ### Removed

  ,

  ### Changed

  , possibly

  ### Added

Pattern: Security Release

• Changes: Security fixes
• Version: PATCH bump (usually) or MAJOR (if breaking)
• Sections:

  ### Security

  ,

  ### Fixed

Troubleshooting

Issue: Version mismatch between files

Issue: Can't determine version bump type

Issue: Changelog format doesn't match existing

@CHANGELOG.md

Issue: Missing changes in changelog

References

• Semantic Versioning 2.0.0
• Keep a Changelog
• Git Documentation