Semantic versioning changelog template with examples

Semantic versioning gives a release number meaning: a major version signals a breaking change, a minor version adds compatible functionality, and a patch version fixes a compatible issue. A changelog should make that meaning useful to the people who need to decide what to do next.

Use this template for a product or API release, then adapt the sections to the changes that customers can actually see or act on.

The template

# [Product name] v[major.minor.patch]

Released: [Month Day, Year]

## Added
- **[Capability]** — [what customers can do now and why it matters].

## Improved
- **[Workflow]** — [what became faster, clearer, or more reliable].

## Fixed
- **[Customer-facing issue]** — [what now works correctly].

## Changed
- **[Behavior or policy]** — [who is affected and what is different].

## Breaking changes
- **[Required action]** — [deadline, migration step, and documentation link].

Do not include every section by default. Empty headings make a release look like a form. Keep the sections that help the reader understand the release.

Minor release example: v2.4.0

A minor release usually adds compatible capability. The release note should lead with the customer outcome, not the version rule.

# Atlas v2.4.0

Released: July 13, 2026

## Added
- **Saved customer views** — save the filters and columns you use most often,
  then reopen that view without rebuilding it.

## Improved
- **Large exports** — customer-list exports are now prepared in the background,
  so you can keep working while the file is generated.

## Fixed
- **Account notifications** — account owners should receive fewer duplicate
  notifications for the same event.

Patch release example: v2.4.1

Patch releases often need less ceremony. If the fix is customer-visible, say what stopped happening and what works now.

# Atlas v2.4.1

Released: July 18, 2026

## Fixed
- **Saved-view permissions** — team members with access to a shared view can now
  open it reliably after an owner updates its filters.

Major release example: v3.0.0

Major versions are where the changelog must be most specific. Put the action required first, name the affected audience, and link directly to migration instructions.

# Atlas v3.0.0

Released: September 1, 2026

## Breaking changes
- **Update API tokens before September 30** — personal API tokens are being
  replaced by scoped service tokens. This affects integrations using the v2 API.
  Follow the [migration guide](https://example.com/migration) to create a new
  token and update your integration.

## Added
- **Scoped service tokens** — give each integration only the permissions it
  needs and revoke access without affecting other automations.

Version numbers do not replace release context

Semantic versioning tells technical users how carefully to evaluate an upgrade. It does not explain the value of the release to an admin, buyer, or day-to-day user. Keep the number, but write the items in product language.

For the standard’s common categories, read the Keep a Changelog format explained. For deciding whether a change needs a major, minor, or patch release, see Conventional Commits vs Changesets.

Generate a clear release update from your shipped GitHub work.