API surface changes documented
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.
# 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.mdfile in the project root. For projects that are published as libraries or packages (checkpackage.jsonfor"private": falseor 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 (versionfield inpackage.jsonfollows semver). Check whether git tags are used for releases. -
Pass criteria: Enumerate all relevant code locations.
CHANGELOG.mdexists 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.mdfollowing the Keep a Changelog format:# 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` insteadConsider using
standard-versionorrelease-pleaseto automate changelog generation from conventional commits.
External references
- iso-25010:2011 · maintainability.analysability — Maintainability — Analysability
Taxons
History
- 2026-04-18·v1.0.0·Initial import from code-quality-essentials·automated