Changelog Generation

Relizy automatically generates beautiful, SEO-friendly changelogs from your git commits.

Overview

Changelogs are generated based on Conventional Commits using the powerful changelogen library.

Automatic Generation

Changelogs are created automatically when you run a release:

bash

relizy release --minor

This generates or updates CHANGELOG.md in your package directory.

Changelog Format

A typical generated changelog looks like this:

# Changelog

## v0.0.0...v0.1.0

### 🚀 Features

- Relizy - release manager ([5c41ba1](https://github.com/LouisMazel/relizy/commit/5c41ba1))

### 📖 Documentation

- Add documentation website of Relizy ([ec156b0](https://github.com/LouisMazel/relizy/commit/ec156b0))

### ❤️ Contributors

- LouisMazel ([@LouisMazel](https://github.com/LouisMazel))

The Contributors section lists the authors of the commits and their co-authors, read from the Co-authored-by: trailers. Contributors of a squash-merged pull request are therefore credited even when the merge commit is authored by the maintainer.

Commit Types

Relizy organizes commits by type:

Type	Emoji	Section	Version Bump
`feat`	🚀	Features	Minor (0.1.0 → 0.2.0)
`fix`	🐛	Bug Fixes	Patch (0.1.0 → 0.1.1)
`perf`	⚡	Performance	Patch
`docs`	📚	Documentation	None
`style`	💅	Styles	None
`refactor`	♻️	Refactors	None
`test`	✅	Tests	None
`build`	📦	Build	None
`ci`	🤖	CI/CD	None
`chore`	🏠	Chores	None

Breaking Changes

Any commit with ! or BREAKING CHANGE: triggers a major version bump:

bash

git commit -m "feat!: redesign API"
# or
git commit -m "feat: redesign API

BREAKING CHANGE: The API has been completely redesigned"

Conventional Commits

To generate meaningful changelogs, follow the Conventional Commits specification:

Basic Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Examples

bash

# Feature
git commit -m "feat: add user authentication"

# Bug fix
git commit -m "fix: resolve memory leak in event handlers"

# With scope
git commit -m "feat(auth): implement OAuth2 login"

# With body
git commit -m "fix: resolve navigation issue

The navigation was broken on mobile devices.
This fix ensures it works correctly on all screen sizes."

# Breaking change
git commit -m "feat!: redesign API

BREAKING CHANGE: The API endpoints have changed.
See migration guide for details."

Customizing Commit Types

You can customize which commit types appear in changelogs and how they're labeled:

// relizy.config.ts
export default defineConfig({
  types: {
    feat: { title: '🎉 New Features', semver: 'minor' },
    fix: { title: '🔧 Bug Fixes', semver: 'patch' },
    perf: { title: '⚡ Performance', semver: 'patch' },
    docs: { title: '📖 Documentation', semver: 'patch' },
    style: { title: '💄 Styling', semver: 'patch' },
    refactor: { title: '🔨 Refactors', semver: 'patch' },
    test: { title: '🧪 Tests', semver: 'patch' },
    build: { title: '📦 Build', semver: 'patch' },
    ci: { title: '🤖 CI/CD', semver: 'patch' },
    chore: { title: '🧹 Chores', semver: 'patch' },
  },
})

Changelog Locations

Single Package

For single packages, the changelog is created at the root:

text

my-package/
├── package.json
├── CHANGELOG.md  ← Generated here
└── src/

Monorepo - Unified Mode

In unified mode, a single changelog is created at the root:

text

my-monorepo/
├── package.json
├── CHANGELOG.md (all changes)
└── packages/
    ├── core/
    │   ├── package.json
    │   └── CHANGELOG.md ← Package-specific
    ├── utils/
    │   ├── package.json
    │   └── CHANGELOG.md ← Package-specific
    └── ui/
        ├── package.json
        └── CHANGELOG.md ← Package-specific

Monorepo - Selective/Independent Mode

In selective or independent modes, each package gets its own changelog:

text

my-monorepo/
├── package.json
├── CHANGELOG.md (all changes)
└── packages/
    ├── core/
    │   ├── package.json
    │   └── CHANGELOG.md  ← Package-specific
    ├── utils/
    │   ├── package.json
    │   └── CHANGELOG.md  ← Package-specific
    └── ui/
        ├── package.json
        └── CHANGELOG.md  ← Package-specific

Generate Changelog Only

You can generate a changelog without bumping versions:

bash

relizy changelog

This is useful for:

Previewing what will be in the next release
Generating changelogs for documentation
Updating changelogs after manual version changes

Version Range

By default, Relizy generates the changelog from the tag of the previous release to HEAD.

The previous release is resolved from the versions, not from the creation date of the tags:

In unified and selective modes (and for a single package), the release tags are the ones following templates.tagBody (v by default), plus the v1.2.3 and 1.2.3 formats. The tags of the packages released independently in the same repository ([email protected]) are never used, so a selective and an independent config can release the same monorepo.
In independent mode, the release tags of a package are its [email protected] tags.
The previous release is the highest version strictly below the version being released (or up to the current version before the bump), and not above its major. A tag created later on another branch, such as the hotfix of an older version or a prerelease of the next one, is never picked instead.
A stable release starts at the previous stable release: a graduation from 2.0.0-beta.3 to 2.0.0 starts at v1.x, not at the last beta.

Changing the tag template

After changing templates.tagBody, the previous v1.2.3 tags are still recognized. If the previous tags followed another custom template, Relizy warns about it: pass the tag of the previous release with --from for the first release with the new template.

You can customize the range:

bash

# From specific version to HEAD
relizy changelog --from v1.0.0

# Between two versions
relizy changelog --from v1.0.0 --to v1.2.0

Excluding Commits

By Type

Exclude specific commit types from changelogs:

// relizy.config.ts
export default defineConfig({
  types: {
    chore: false, // Don't include chores in changelog
    ci: false, // Don't include CI commits
  },
})

By Pattern

Exclude commits matching patterns:

// relizy.config.ts
export default defineConfig({
  excludeAuthors: [
    'dependabot[bot]',
    'renovate[bot]',
  ],
})

GitHub/GitLab Integration

Relizy automatically creates clickable links to commits and comparisons:

### 🚀 Features

- Add authentication ([a1b2c3d](https://github.com/user/repo/commit/a1b2c3d))

The git remote is auto-detected from your repository.

Changelog Title

By default, the changelog section title shows v1.1.0...v1.2.0. You can customize it with the templates.changelogTitle option:

// relizy.config.ts
export default defineConfig({
  templates: {
    // Show only the new version
    changelogTitle: '{{newVersion}}',
    // Or include the date
    // changelogTitle: '{{newVersion}} ({{date}})',
  },
})

Available variables: {{oldVersion}}, {{newVersion}}, {{date}}.

See Changelog Configuration for more details.

Changelog Output

Markdown Files

Changelogs are written to CHANGELOG.md:

# Changelog

## v1.1.0...v1.2.0

[compare](https://github.com/user/repo/compare/v1.1.0...v1.2.0)

...

JSON Output

You can also output changelogs as JSON:

bash

relizy changelog

json

{
  "releases": [
    {
      "version": "1.2.0",
      "date": "2024-03-15",
      "commits": [
        {
          "type": "feat",
          "scope": "auth",
          "message": "add user authentication",
          "sha": "a1b2c3d"
        }
      ]
    }
  ]
}

Best Practices

1. Write Good Commit Messages

bash

# Good ✅
git commit -m "feat(auth): implement OAuth2 login"
git commit -m "fix: resolve memory leak in event handlers"

# Bad ❌
git commit -m "stuff"
git commit -m "fixes"
git commit -m "updated things"

2. Use Scopes for Organization

Scopes help group related changes:

bash

git commit -m "feat(ui): add dark mode"
git commit -m "feat(api): add REST endpoints"
git commit -m "fix(database): resolve connection pooling issue"

3. Add Descriptive Bodies

For complex changes, add details:

bash

git commit -m "feat: implement caching layer

Added Redis caching for API responses to improve performance.
Cache TTL is configurable via environment variables."

4. Mark Breaking Changes Clearly

Always document breaking changes:

bash

git commit -m "feat!: redesign authentication API

BREAKING CHANGE: The authentication endpoints have changed.
Old endpoint: POST /login
New endpoint: POST /api/v2/auth/login

Migration guide: docs/migration.md"

5. Keep Changelogs Clean

Exclude noise from changelogs:

// relizy.config.ts
export default defineConfig({
  types: {
    ci: false, // Skip CI commits
    chore: false, // Skip chores
  },
  excludeAuthors: [
    'dependabot[bot]',
  ],
})

Examples

Basic Usage

bash

# Generate changelog as part of release
relizy release --minor

# Generate changelog without version bump
relizy changelog

Custom Range

bash

# Changelog from v1.0.0 to v2.0.0
relizy changelog --from v1.0.0 --to v2.0.0

# Changelog for last 10 commits
relizy changelog --from HEAD~10

Monorepo

bash

# Generate changelogs for all packages
relizy changelog

Configuration

Full changelog configuration options:

// relizy.config.ts
export default defineConfig({
  // Commit types
  types: {
    feat: { title: '🚀 Features', semver: 'minor' },
    fix: { title: '🐛 Bug Fixes', semver: 'patch' },
  },

  // Excluded authors
  excludeAuthors: ['dependabot[bot]'],

  // GitHub/GitLab URLs
  github: 'user/repo',
  // or
  gitlab: 'user/repo',

  // Version range
  from: 'v1.0.0',
  to: 'HEAD',
})

Next Steps

Getting Started - Learn basic usage
CLI Reference - Changelog command details
Configuration - Advanced changelog options

Changelog Generation ​

Overview ​

Automatic Generation ​

Changelog Format ​

Commit Types ​

Breaking Changes ​

Conventional Commits ​

Basic Format ​

Examples ​

Customizing Commit Types ​

Changelog Locations ​

Single Package ​

Monorepo - Unified Mode ​

Monorepo - Selective/Independent Mode ​

Generate Changelog Only ​

Version Range ​

Excluding Commits ​

By Type ​

By Pattern ​

GitHub/GitLab Integration ​

Changelog Title ​

Changelog Output ​

Markdown Files ​

JSON Output ​

Best Practices ​

1. Write Good Commit Messages ​

2. Use Scopes for Organization ​

3. Add Descriptive Bodies ​

4. Mark Breaking Changes Clearly ​

5. Keep Changelogs Clean ​

Examples ​

Basic Usage ​

Custom Range ​

Monorepo ​

Configuration ​

Next Steps ​

Changelog Generation

Overview

Automatic Generation

Changelog Format

Commit Types

Breaking Changes

Conventional Commits

Basic Format

Examples

Customizing Commit Types

Changelog Locations

Single Package

Monorepo - Unified Mode

Monorepo - Selective/Independent Mode

Generate Changelog Only

Version Range

Excluding Commits

By Type

By Pattern

GitHub/GitLab Integration

Changelog Title

Changelog Output

Markdown Files

JSON Output

Best Practices

1. Write Good Commit Messages

2. Use Scopes for Organization

3. Add Descriptive Bodies

4. Mark Breaking Changes Clearly

5. Keep Changelogs Clean

Examples

Basic Usage

Custom Range

Monorepo

Configuration

Next Steps