Changelog Command

The buddy changelog command generates a CHANGELOG.md file based on your conventional commit history, providing a clear record of changes across versions.

Basic Usage

buddy changelog

Command Syntax

buddy changelog [options]

Options

Examples

Generate Changelog

buddy changelog

Output:

buddy changelog

Generated CHANGELOG.md

Completed in 0.89s

Preview Changes (Dry Run)

buddy changelog --dry-run

This shows what would be written without modifying the file.

Quiet Mode

buddy changelog --quiet

Minimal output, useful for CI/CD.

Verbose Output

buddy changelog --verbose

Shows detailed information about processing.

Changelog Format

The generated changelog follows the Keep a Changelog format:

# Changelog

All notable changes to this project will be documented in this file.

## [Unreleased]

## [1.2.0] - 2024-01-15

### Added

- Add user dashboard (#123)
- Implement dark mode (#124)

### Fixed

- Fix login timeout issue (#125)
- Resolve database connection leak (#126)

### Changed

- Update dependency versions
- Improve error messages

## [1.1.0] - 2024-01-01

### Added

- Initial authentication system
- Basic CRUD operations

Commit Type Mapping

Conventional commits are mapped to changelog sections:

Breaking Changes

Breaking changes are highlighted prominently:

## [2.0.0] - 2024-02-01

### BREAKING CHANGES

- API response format changed from object to array
- Removed deprecated authentication methods

### Added

- New REST API endpoints

Configuration

Changelog generation can be configured in your project:

// config/changelog.ts
export default {
  // Sections to include
  sections: ['Added', 'Fixed', 'Changed', 'Removed'],

  // Skip certain types
  skipTypes: ['chore', 'ci'],

  // Custom header
  header: '# Project Changelog\n\nAll notable changes are documented here.',
}

Workflow Integration

Before Releases

Generate changelog before releasing:

buddy changelog
buddy release

Automated Updates

In CI/CD, update changelog automatically:

# .github/workflows/release.yml

- name: Generate Changelog

  run: buddy changelog

- name: Commit Changelog

  run: |
    git add CHANGELOG.md
    git commit -m "docs: update changelog"
    git push

Best Practices

Write Good Commit Messages

The changelog quality depends on commit messages:

Good commits produce good changelogs:

feat(auth): add two-factor authentication support

- Add TOTP generation
- Add backup codes
- Add QR code display

Bad commits produce unclear changelogs:

update auth
fix stuff

Use Scopes

Scopes help organize the changelog:

feat(api): add rate limiting
feat(ui): implement dark mode
fix(auth): resolve token expiration bug

Reference Issues

Link to issues for more context:

fix(cart): resolve checkout race condition (#456)

Keep Entries Concise

Good changelog entries are:

• Clear and concise
• Written in imperative mood
• Focused on the "what", not "how"

Troubleshooting

No Commits Found

Warning: No commits found since last release

Solution: Ensure you have conventional commits:

# Check recent commits
git log --oneline -10

# Make commits with proper format
buddy commit

File Permission Error

Error: Cannot write to CHANGELOG.md

Solution:

chmod 644 CHANGELOG.md
buddy changelog

Missing Version Tags

Warning: No version tags found

Solution: Create an initial tag:

git tag v0.0.1
buddy changelog

Incorrect Dates

Dates come from git tags. If incorrect:

# Check tag dates
git tag -l --format='%(refname:short) %(creatordate:short)'

Manual Editing

While the changelog is auto-generated, you can manually edit it:

1. Run buddy changelog
2. Review CHANGELOG.md
3. Add clarifications or context
4. Keep edits in dedicated sections

## [1.2.0] - 2024-01-15

### Added

- Add user dashboard (#123)

### Notes
> This release includes significant UI improvements.
> Please report any issues via GitHub.

Related Commands

• buddy commit - Create conventional commits
• buddy release - Create releases
• buddy version - View version information