# Public changelog exists

- **Pattern:** `ab-001012` (`developer-documentation.maintenance.changelog`)
- **Severity:** medium
- **Lifecycle:** active
- **Last modified:** 2026-04-18
- **Canonical URL:** https://auditbuffet.com/patterns/ab-001012
- **License:** CC-BY-4.0 — attribute to AuditBuffet Pattern Catalog (https://auditbuffet.com/patterns/ab-001012)

## Why it matters

No changelog means users have no reliable way to know what changed between versions, whether a bug they hit is fixed, or whether upgrading is safe. A changelog that stops at v1.2.0 when the project is now on v2.1.0 is a signal that the project is poorly maintained — the same signal that drives dependency abandonment decisions. iso-25010:2011 analysability covers this: a project where change history is opaque requires source-level investigation to understand its evolution. Following Keep a Changelog format provides a predictable structure that users can parse quickly for the entries that matter to them.

## Severity rationale

Medium because the absence of a changelog doesn't block initial use but degrades confidence in the project's maintenance posture and makes upgrade decisions opaque, compounding over time.

## Remediation

Create `CHANGELOG.md` at the project root following [Keep a Changelog](https://keepachangelog.com/) format. The latest entry must match the version in `package.json`:

```markdown
# Changelog

## [2.1.0] - 2026-03-15

### Added
- New `query()` method replacing `fetchData()`
- TypeScript type exports for all public types

### Fixed
- Connection timeout now throws instead of hanging indefinitely

## [2.0.0] - 2026-02-01

### Changed
- BREAKING: Renamed `fetchData()` to `query()`
- Minimum Node.js version bumped to 18

### Removed
- CommonJS import support dropped
```

A changelog without dates, version numbers, or change categorization fails this check. An outdated changelog (not updated for the current version) also fails.

## Detection

- **ID:** `changelog`
- **Severity:** `medium`
- **What to look for:** Check for CHANGELOG.md at the project root, a "Releases" page on GitHub/GitLab, or a changelog section in the documentation. Verify it lists changes per version with dates, categorized by type (added, changed, fixed, removed). Check that it is current -- the latest version in the changelog should match the current project version. Count all instances found and enumerate each.
- **Pass criteria:** A changelog exists, is current (includes the latest version), and categorizes changes by type. Each entry has a version number and date. The format follows Keep a Changelog or similar convention. At least 1 implementation must be confirmed.
- **Fail criteria:** No changelog exists, or it exists but is outdated (missing recent versions), or changes are listed without version numbers or dates.
- **Skip (N/A) when:** The project is pre-release (0.x) with fewer than 3 published versions.
- **Detail on fail:** Example: `"No CHANGELOG.md exists and no GitHub Releases page is configured"` or `"CHANGELOG.md last entry is v1.2.0 from 2024-06-01 but current version is v2.1.0"`
- **Remediation:** Create a changelog following [Keep a Changelog](https://keepachangelog.com/) format:

  ```markdown
  # Changelog

  ## [2.1.0] - 2026-03-15

  ### Added
  - New `query()` method for flexible data fetching
  - TypeScript type exports for all public types

  ### Fixed
  - Connection timeout now properly throws instead of hanging

  ## [2.0.0] - 2026-02-01

  ### Changed
  - BREAKING: Renamed `fetchData()` to `query()`
  - Minimum Node.js version bumped to 18

  ### Removed
  - Dropped support for CommonJS imports
  ```

## External references

- iso-25010 maintainability.analysability

Taxons: code-quality

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