# CHANGELOG with entries per version

- **Pattern:** `ab-002379` (`sdk-package-quality.docs-maintenance.changelog`)
- **Severity:** high
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002379
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002379)

## Why it matters

Consumers upgrading from `v1.x` to `v2.x` need to know what broke and what migrated. Without a `CHANGELOG.md`, they must diff the entire package history, read all commit messages, or trial-upgrade hoping nothing explodes. ISO 25010 modifiability requires that the system's evolution be trackable. A changelog is also a trust signal: maintained packages have changelogs; abandoned packages don't. For packages consumed in regulated or enterprise environments, documented version history is often a procurement requirement.

## Severity rationale

High because consumers cannot safely assess upgrade risk without documented version history, leading to either blocked upgrades (security debt) or blind upgrades (breakage risk).

## Remediation

Create `CHANGELOG.md` in the project root following the Keep a Changelog format, with one entry per released version.

```markdown
# Changelog

## [2.3.1] - 2026-03-15

### Fixed
- Fixed retry logic that caused duplicate requests on timeout

## [2.3.0] - 2026-03-01

### Added
- New `retryConfig` option for customizing retry behavior

### Changed
- Default timeout increased from 5s to 10s
```

The most recent entry must match the current `version` in `package.json`. For teams using conventional commits, `conventional-changelog` or `release-it` can generate this automatically on each release. Keep a changelog even if you use GitHub Releases — not all consumers browse GitHub.

## Detection

- **ID:** `changelog`
- **Severity:** `high`
- **What to look for:** List all changelog or release documentation files. check for `CHANGELOG.md` (or `CHANGES.md`, `HISTORY.md`) in the project root. Verify:
  1. The file exists
  2. It has entries organized by version number
  3. Entries describe what changed (not just "bug fixes" or "updates")
  4. The most recent version in the changelog matches `version` in `package.json`
  5. Format follows a convention (Keep a Changelog, Conventional Changelog, or similar)
- **Pass criteria:** A changelog file exists with at least one version entry that describes changes. The most recent entry's version matches or is close to the current `package.json` version — at least 1 CHANGELOG.md or GitHub Releases with entries for the current version. Report: "X changelog entries found."
- **Fail criteria:** No changelog file exists, OR the changelog exists but is empty or contains only a template with no actual entries, OR the most recent changelog entry is more than 2 major versions behind `package.json` version (abandoned changelog).
- **Skip (N/A) when:** The package is at version `0.0.x` or `0.1.0` (first release, no prior versions to document). Also skip if `version` in `package.json` is exactly `1.0.0` and no prior versions were published.
- **Detail on fail:** `"No CHANGELOG.md found. package.json version is 2.3.1 — consumers upgrading from older versions have no way to know what changed or what might break."`
- **Remediation:** A changelog helps consumers decide whether to upgrade and what to watch for.

  ```markdown
  # Changelog

  ## [2.3.1] - 2026-03-15

  ### Fixed
  - Fixed retry logic that caused duplicate requests on timeout

  ## [2.3.0] - 2026-03-01

  ### Added
  - New `retryConfig` option for customizing retry behavior

  ### Changed
  - Default timeout increased from 5s to 10s
  ```

  Follow [Keep a Changelog](https://keepachangelog.com) format. If you use conventional commits, tools like `conventional-changelog` can generate this automatically.

## External references

- iso-25010 maintainability.modifiability

Taxons: code-quality

HTML version: https://auditbuffet.com/patterns/ab-002379