Changelog¶

All notable changes to this project are documented in this file. The changelog is automatically generated by semantic-release based on commit messages.

Auto-generated Content

This changelog is automatically generated from commit messages following Conventional Commits. Do not edit manually.

How It Works¶

The changelog is generated automatically when:

Commits are pushed to the main branch
Commit messages follow Conventional Commits format
The semantic-release workflow determines version bumps
Changelog entries are created and grouped by type

Changelog Format¶

Entries are organized by:

Version number (following semantic versioning)
Release date
Change type (Features, Bug Fixes, etc.)
Links to commits and pull requests

Entry Types¶

Commit Type	Changelog Section	Example
`feat:`	Features	New functionality added
`fix:`	Bug Fixes	Bugs that were fixed
`perf:`	Performance	Performance improvements
`revert:`	Reverts	Reverted changes

Other Types

Commits with types like docs:, style:, refactor:, test:, and chore: don't appear in the changelog but still follow Conventional Commits format.

Current Changelog¶

The current changelog is maintained in the root CHANGELOG.md file. Below is a recent excerpt:

1.16.0 (2026-02-03)¶

Features¶

remove deprecated extension (60bdcb9)

1.15.0 (2026-01-23)¶

Features¶

Update template-repo-sync.yaml (bc814fe)

1.14.0 (2026-01-17)¶

Bug Fixes¶

Allow automerge for branch patterns regardless of actor (#84) (5ee45ef)

Features¶

Change license update script to use repo owner (956ca67)

1.13.2 (2026-01-12)¶

Bug Fixes¶

Update gitleaks.yaml (c04fd31)

View Full Changelog

View the complete changelog in the CHANGELOG.md file in the repository root.

Understanding Versions¶

This project follows Semantic Versioning (SemVer):

MAJOR.MINOR.PATCH

Version Components¶

MAJOR (Breaking Changes) - Incompatible API changes - Breaking changes in behavior - Requires user action to upgrade - Triggered by: BREAKING CHANGE: in footer or ! after type

Example:

feat!: redesign API endpoints

BREAKING CHANGE: All endpoints now require authentication

MINOR (New Features) - New functionality added - Backwards-compatible changes - No breaking changes - Triggered by: feat: commit type

Example:

feat: add OAuth2 authentication

PATCH (Bug Fixes) - Bug fixes and minor improvements - Backwards-compatible fixes - Performance improvements - Triggered by: fix:, perf:, revert: commit types

Example:

fix: resolve null pointer exception in user endpoint

Changelog Best Practices¶

Writing Changelog-Friendly Commits¶

Good Examples¶

# Clear, descriptive feature
feat(auth): add OAuth2 authentication with Google and GitHub providers

# Specific bug fix
fix(api): resolve null pointer exception when user email is null

# Performance improvement
perf(db): optimize user query with database indexes

Poor Examples¶

# Too vague
feat: add stuff

# Not descriptive
fix: fix bug

# Wrong type (should be feat)
update: add new feature

Creating Meaningful Entries¶

Include Context in Body¶

feat(auth): add password reset functionality

Implements password reset flow with email verification.
Users receive a time-limited reset link via email.
Includes rate limiting to prevent abuse.

Closes #142

This creates a detailed changelog entry:

### Features

* **auth:** add password reset functionality ([abc123](link))

  Implements password reset flow with email verification.
  Users receive a time-limited reset link via email.
  Includes rate limiting to prevent abuse.

  Closes #142

Link Issues¶

Always link related issues:

feat: add user dashboard

Closes #123
Fixes #456
Refs #789

This creates clickable links in the changelog.

Changelog Generation Process¶

1. Analyze Commits¶

Semantic-release analyzes commits since the last release:

# Commits analyzed
fix(api): resolve bug
feat(ui): add new component
docs: update README

2. Determine Version¶

Based on commit types:

Has feat:? → Minor bump (1.0.0 → 1.1.0)
Has fix: only? → Patch bump (1.0.0 → 1.0.1)
Has BREAKING CHANGE:? → Major bump (1.0.0 → 2.0.0)
Only docs:, chore:? → No release

3. Generate Notes¶

Group commits by type:

# [1.1.0] (2024-03-15)

### Features
* **ui:** add new component ([abc123](link))

### Bug Fixes
* **api:** resolve bug ([def456](link))

4. Update Files¶

Update CHANGELOG.md
Create GitHub release
Create git tag
Commit changes

Customizing Changelog¶

Change Grouping¶

Edit .releaserc.json:

{
  "plugins": [
    ["@semantic-release/release-notes-generator", {
      "preset": "angular",
      "presetConfig": {
        "types": [
          {"type": "feat", "section": "✨ Features"},
          {"type": "fix", "section": "🐛 Bug Fixes"},
          {"type": "perf", "section": "⚡ Performance"},
          {"type": "docs", "section": "📚 Documentation", "hidden": false}
        ]
      }
    }]
  ]
}

Add Emojis¶

{
  "presetConfig": {
    "types": [
      {"type": "feat", "section": "✨ Features"},
      {"type": "fix", "section": "🐛 Bug Fixes"},
      {"type": "perf", "section": "⚡ Performance"},
      {"type": "revert", "section": "⏪ Reverts"}
    ]
  }
}

Custom Commit Types¶

Include additional commit types:

{
  "presetConfig": {
    "types": [
      {"type": "feat", "section": "Features"},
      {"type": "fix", "section": "Bug Fixes"},
      {"type": "docs", "section": "Documentation", "hidden": false},
      {"type": "style", "section": "Styling", "hidden": false},
      {"type": "refactor", "section": "Refactoring", "hidden": false}
    ]
  }
}

Changelog Workflow¶

For Contributors¶

Write conventional commits
```
git commit -m "feat: add new feature"
```
Push to branch
```
git push origin feat/my-feature
```
Create pull request
PR title must follow Conventional Commits
Changelog will be generated on merge

For Maintainers¶

Review and merge PR
Verify PR title is conventional
Squash and merge (preserves PR title)
Automatic release
Release workflow runs automatically
Changelog is updated
GitHub release is created
Tag is pushed
Verify release
Check Releases tab
Verify CHANGELOG.md
Confirm version tag

Viewing Changelog¶

In Repository¶

File: CHANGELOG.md in repository root

# View locally
cat CHANGELOG.md

# View in browser
https://github.com/username/repo/blob/main/CHANGELOG.md

In Releases¶

GitHub Releases: Repository → Releases tab

Each release includes:

Version number and date
Release notes (from changelog)
Links to commits
Download links for source code

In Documentation¶

This page: Changelog

A curated view of recent changes with context and explanations.

Common Questions¶

Why isn't my commit in the changelog?¶

Reason: Only certain commit types appear in the changelog: - feat: - Appears in Features section - fix: - Appears in Bug Fixes section - perf: - Appears in Performance section - Other types (docs:, chore:, etc.) are hidden by default

How do I fix a wrong changelog entry?¶

Don't edit CHANGELOG.md manually. Instead:

The entry is based on commit messages
Use git revert to undo changes
Make a new commit with the correct message
The next release will include the correction

Can I skip a release?¶

Yes, using skip keywords:

git commit -m "docs: update README [skip ci]"

Or in PR title:

docs: update README [skip release]

How do I create a pre-release?¶

Configure beta/alpha branches in .releaserc.json:

{
  "branches": [
    "main",
    {"name": "beta", "prerelease": true}
  ]
}

Additional Resources¶

Semantic Versioning - Version numbering specification
Conventional Commits - Commit message convention
Keep a Changelog - Changelog best practices
Semantic Release - Automated releases
Commit Conventions - Detailed commit guide

Questions? Open a discussion.