/generate-changelog

Automatically generate a changelog from your commit history and pull requests using conventional commits and Keep a Changelog format.

Quick Start

Copy/agileflow:generate-changelog VERSION=2.5.0 SINCE=v2.4.0

Purpose

This command creates professional changelogs by:

• Detecting version from latest git tags automatically
• Collecting commits and merged PRs since last release
• Categorizing changes (Added/Changed/Fixed/Removed/Security)
• Highlighting breaking changes
• Suggesting semantic versions based on changes
• Updating CHANGELOG.md with proper formatting
• Optionally creating git tags and GitHub releases

Parameters

Examples

Auto-Detect Everything

Copy/agileflow:generate-changelog

Uses latest tag as version start, detects next version, and generates changelog.

Specify Exact Versions

Copy/agileflow:generate-changelog VERSION=2.5.0 SINCE=v2.4.0

Creates changelog section for version 2.5.0 from commits since v2.4.0.

Use GitHub Format

Copy/agileflow:generate-changelog FORMAT=github

Generates changelog in GitHub release notes format.

Auto-Commit Changes

Copy/agileflow:generate-changelog AUTO_COMMIT=yes

Updates CHANGELOG.md and commits automatically after your confirmation.

How It Works

The command follows a smart workflow:

1. Version Detection

If VERSION not provided, detects from git:

Copygit describe --tags --abbrev=0  # Gets latest tag

Then suggests next version based on changes:

• Major (2.0.0): Breaking changes detected
• Minor (1.X.0): New features (feat:) only
• Patch (1.1.X): Bug fixes (fix:) only

2. Commit Collection

Gathers commits since SINCE point:

Copygit log <SINCE>..HEAD --oneline --no-merges

Also fetches merged PRs from GitHub:

Copygh pr list --state merged --json number,title,mergedAt,labels

3. Categorization

Automatically categorizes using conventional commits:

4. Changelog Generation

Creates entry in Keep a Changelog format:

Copy## [2.5.0] - 2025-12-22
 
### Added
- OAuth2 authentication support (#123)
- Dark mode toggle (#137)
 
### Changed
- ⚠️ **BREAKING**: Redesigned API endpoints (#126)
- Improved query performance by 50% (#125)
 
### Fixed
- Crash when user is null (#124)
- Memory leak in WebSocket handler (#139)
 
### Security
- Patched XSS vulnerability in comment rendering (#131)

5. User Review and Approval

Shows diff preview and asks for confirmation before updating CHANGELOG.md.

6. Optional Actions

If approved:

• Updates CHANGELOG.md
• Optionally creates git commit
• Can create git tag
• Can create GitHub release

Changelog Format

The command uses Keep a Changelog standard with these sections:

[Unreleased]

Development changes not yet released (always stays at top)

[VERSION] - DATE

Sections for each release:

• Added - New functionality
• Changed - Changes to existing functionality
• Deprecated - Soon-to-be removed functionality
• Removed - Removed functionality
• Fixed - Bug fixes
• Security - Security vulnerability fixes

Breaking Changes

Breaking changes are detected and highlighted prominently:

Detected By:

• Commit with ! after type: feat!: redesign API
• Commit with BREAKING CHANGE: footer
• PR labeled with breaking-change

Displayed As:

Copy### Changed
- ⚠️ **BREAKING**: Redesigned API endpoints. See migration guide. (#126)

Output File

The command updates CHANGELOG.md with this structure:

Copy# Changelog
 
All notable changes to this project will be documented in this file.
 
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
## [Unreleased]
 
## [2.5.0] - 2025-12-22
### Added
...
 
## [2.4.0] - 2025-11-15
### Added
...
 
---
 
[unreleased]: https://github.com/user/repo/compare/v2.5.0...HEAD
[2.5.0]: https://github.com/user/repo/compare/v2.4.0...v2.5.0
[2.4.0]: https://github.com/user/repo/compare/v2.3.0...v2.4.0

Workflow

The complete workflow looks like this:

1. Show Detection Results

   Latest tag: v2.4.0
   Commits since: 15 (3 Added, 5 Fixed, 2 Changed, 1 Security)
   Suggested version: 2.5.0 (MINOR - new features)
   

2. Show Changelog Preview

   ## [2.5.0] - 2025-12-22
   
   ### Added
   - OAuth2 authentication support (#123)
   ...
   

3. Ask for Confirmation

   Update CHANGELOG.md? (YES/NO)
   Auto-commit? (YES/NO)
   Create tag? (YES/NO)
   

4. Apply Changes

   • Updates CHANGELOG.md
   • Optionally commits: git commit -m "chore(release): update CHANGELOG for v2.5.0"
   • Optionally creates tag: git tag -a v2.5.0
   • Optionally creates GitHub release

Integration with CI/CD

You can automate changelog generation in CI:

Copyname: Release
 
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version number (e.g., 1.2.0)'
        required: true
 
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Get all tags
 
      - name: Generate changelog
        run: /agileflow:generate-changelog VERSION=${{ github.event.inputs.version }}
 
      - name: Commit changelog
        run: |
          git config user.name "github-actions"
          git config user.email "actions@github.com"
          git add CHANGELOG.md
          git commit -m "chore(release): update CHANGELOG"
 
      - name: Create tag
        run: git tag -a v${{ github.event.inputs.version }} -m "Release v${{ github.event.inputs.version }}"
 
      - name: Push changes
        run: git push origin main && git push origin v${{ github.event.inputs.version }}
 
      - name: Create GitHub release
        run: gh release create v${{ github.event.inputs.version }} --generate-notes
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Best Practices

Commit Message Format

Use conventional commits for automatic categorization:

Copy# Good - auto-categorizes as Added
git commit -m "feat: add OAuth2 authentication"
 
# Good - auto-categorizes as Fixed
git commit -m "fix: crash when user is null"
 
# Good - breaking change detection
git commit -m "feat!: redesign API endpoints"
 
# Better - with scope
git commit -m "feat(auth): add OAuth2 support"

Semantic Versioning

Follow semantic versioning after releases:

CopyMAJOR.MINOR.PATCH
  2  .  5  .  0
 
- MAJOR: Breaking changes
- MINOR: New features (backwards compatible)
- PATCH: Bug fixes only

Release Process

1. Generate changelog for next version
2. Create git tag with version
3. Push tag to trigger CD pipeline
4. Create GitHub release with changelog excerpt
5. Announce release (blog, social media, newsletter)

Related Commands

• /ci-setup - Set up CI/CD workflow
• /setup-deployment - Configure deployment
• /agileflow:status - View project status