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.
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.
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.
ID: code-quality-essentials.dependencies.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:
# 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.