# API surface changes documented

- **Pattern:** `ab-002154` (`code-quality-essentials.dependencies.breaking-changes-doc`)
- **Severity:** info
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-002154
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-002154)

## Why it matters

Published libraries without a changelog force consumers to diff two arbitrary git SHAs to understand what changed between versions — or to discover breaking changes at runtime after an upgrade. ISO 25010:2011 §6.5.2 classifies undocumented API surface changes as a maintainability defect. For internal applications this is low priority, but any package with `"private": false` or published `"exports"` fields is making an implicit promise to consumers that it does not keep when it ships breaking changes silently.

## Severity rationale

Info because missing changelog documentation does not affect runtime behavior but removes the audit trail that lets consumers make informed upgrade decisions for published libraries.

## Remediation

Add a `CHANGELOG.md` at the repo root following the Keep a Changelog format. Include a "Breaking Changes" section for any major or minor releases that remove or modify public API behavior.

```markdown
# Changelog

## [Unreleased]

## [1.2.0] - 2024-03-15
### Added
- New `formatCurrency` utility function

### Changed
- `parseDate` now returns `null` instead of throwing on invalid input

### Breaking Changes
- Removed deprecated `formatMoney` function; use `formatCurrency` instead
```

Consider `release-please` or `standard-version` to generate changelog entries automatically from conventional commits.

## Detection

- **ID:** `breaking-changes-doc`
- **Severity:** `info`
- **What to look for:** Check for a `CHANGELOG.md` file in the project root. For projects that are published as libraries or packages (check `package.json` for `"private": false` or presence of `"main"`, `"exports"`, `"files"` fields), a changelog is important for consumers to understand breaking changes. For internal applications, this is informational — nice to have but not critical. Look for semantic versioning in use (`version` field in `package.json` follows semver). Check whether git tags are used for releases.
- **Pass criteria:** Enumerate all relevant code locations. `CHANGELOG.md` exists and documents version history, OR project is an internal application (not a published library) with at least 1 verified location.
- **Fail criteria:** Project is a published library without a changelog.
- **Skip (N/A) when:** Internal application, not a library or public API.
- **Detail on fail:** `"No CHANGELOG.md found; consumers of this library cannot track breaking changes between versions"`
- **Remediation:** Add a `CHANGELOG.md` following the Keep a Changelog format:

  ```markdown
  # Changelog

  ## [Unreleased]

  ## [1.2.0] - 2024-03-15
  ### Added
  - New `formatCurrency` utility function

  ### Changed
  - `parseDate` now returns `null` instead of throwing on invalid input

  ### Breaking Changes
  - Removed deprecated `formatMoney` function; use `formatCurrency` instead
  ```

  Consider using `standard-version` or `release-please` to automate changelog generation from conventional commits.

---

## External references

- iso-25010 maintainability.analysability

Taxons: code-quality

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