# Version history shows semver compliance

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

## Why it matters

A package stuck at `version: 1.0.0` (the `npm init` default) with no changelog and no git tags has never been intentionally versioned. Consumers cannot tell whether `1.0.0` is stable or a placeholder, and cannot specify version constraints in their `package.json` with any confidence. Worse, breaking API changes shipped without a major bump silently break consumers on `npm update` — the canonical semver violation. ISO 25010 modifiability requires that the package's evolution be communicated through its version number.

## Severity rationale

High because breaking changes without major version bumps silently break consumer projects on routine dependency updates, with no warning from the version range they specified.

## Remediation

Set an intentional version and commit to the semver contract.

```json
// Start at 0.1.0 if not yet stable, 1.0.0 when you're ready to commit to backward compat:
{ "version": "0.1.0" }
```

Semver rules:
- **MAJOR** (2.0.0): any breaking API change — removed export, changed parameter types, renamed symbol
- **MINOR** (1.1.0): new exports or features, backward-compatible
- **PATCH** (1.0.1): bug fixes, no API changes

Use `npm version patch|minor|major` to bump — it updates `package.json` and creates a git tag automatically. Version `0.0.0` or a placeholder that was never bumped intentionally fails this check.

## Detection

- **ID:** `semver`
- **Severity:** `high`
- **What to look for:** Count all version references across package.json and changelog. examine the version in `package.json` and the version history (in changelog, git tags, or npm version history). Check:
  1. Current version follows semver format (MAJOR.MINOR.PATCH)
  2. Version is not `0.0.0` or `0.0.1` (suggests never intentionally versioned)
  3. If breaking changes are documented in the changelog, they're accompanied by a major version bump
  4. The version is not stuck at `1.0.0` with many subsequent changes (never bumped)
  For Python: check PEP 440 version format. For Rust: semver is enforced by cargo.
- **Pass criteria:** The `version` field follows semantic versioning format. If a changelog exists, breaking changes correspond to major version bumps, new features to minor bumps, and fixes to patch bumps — version must follow semver format (MAJOR.MINOR.PATCH) with at least 3 numeric segments. Report: "Version X.Y.Z follows semver conventions."
- **Fail criteria:** Version is not valid semver, OR version is `0.0.0`/`0.0.1` (never intentionally set), OR the changelog documents breaking changes without corresponding major bumps, OR `package.json` still has the default `"version": "1.0.0"` with no evidence of any versioning thought (no tags, no changelog entries, no published versions).
- **Skip (N/A) when:** Never — every published package has a version.
- **Do NOT pass when:** The version is 0.0.0 or a placeholder — published packages must have a meaningful version.
- **Detail on fail:** `"Version is 1.0.0 (npm init default) with no changelog entries, no git tags, and no published versions. The version has never been intentionally set or bumped."`
- **Remediation:** Semantic versioning communicates compatibility to consumers. Follow the rules:
  - MAJOR (2.0.0): breaking API changes — consumers may need to update their code
  - MINOR (1.1.0): new features, backward-compatible
  - PATCH (1.0.1): bug fixes, backward-compatible

  ```json
  // Set an intentional first version:
  { "version": "0.1.0" }
  ```

  Use `npm version patch|minor|major` to bump versions. This updates `package.json` and creates a git tag automatically.

## External references

- iso-25010 maintainability.modifiability
- ssdf PS.3.2

Taxons: code-quality

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