paulund

Changelog

Changelog

A changelog is a human-readable record of the changes made to a project over time. It helps users understand what is new, what has changed, and what has been fixed -- without them needing to read the commit history or release notes in full.

The Keep a Changelog Format

The most widely adopted changelog convention is Keep a Changelog. It prescribes a simple structure:

  • Entries are grouped by version number.
  • Each version is sorted with the most recent at the top.
  • Changes within a version are organised under one or more of the following category headings:
Category Use it for
Added New features or capabilities.
Changed Changes to existing functionality.
Deprecated Features that still work but will be removed in a future release.
Removed Features or capabilities that have been taken out.
Fixed Bug fixes.
Security Fixes or changes that address a security vulnerability.

An Unreleased section at the top collects changes that have been merged but not yet shipped in a tagged release.

What to Log

Log anything a user or developer consuming your project would care about. Specifically:

  • New features that change what the software can do.
  • Breaking changes that require action from users (highlight these prominently).
  • Bug fixes that correct visible or impactful behaviour.
  • Security patches.

Do not log internal refactoring, test changes, or CI tweaks unless they affect the public API or user-facing behaviour.

Template

Place a file named CHANGELOG.md at the root of your repository. Use the following structure:

# 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]

### Added

- [Description of new feature.]

### Changed

- [Description of change.]

### Fixed

- [Description of bug fix.]

---

## [1.2.0] - 2026-01-15

### Added

- User profile avatars on the account settings page.
- CSV export option for the sales dashboard.

### Fixed

- Corrected date formatting in email notifications for non-UTC timezones.

## [1.1.0] - 2025-11-20

### Added

- Dark mode toggle in application preferences.

### Changed

- Replaced the legacy payment gateway with the updated Stripe integration.

## [1.0.0] - 2025-09-01

### Added

- Initial public release.

Tips

  • Update the changelog as you work, not after the fact. The Unreleased section exists precisely for this purpose.
  • Automate where possible. Tools such as conventional-changelog can generate changelog entries from Conventional Commits.
  • Link version headings to the corresponding Git tags or GitHub release pages so readers can jump straight to the diff.