# Changelog Desk

> Check one project's CHANGELOG.md against Keep a Changelog 1.1.0, compute the next Semantic
> Versioning 2.0.0 version from the Conventional Commits since the last release, and write the
> new release for the people upgrading. The checks and the version arithmetic run free in the
> browser; the review and the draft are metered model runs whose every line the page checks again.

Live app: https://changelog-desk.skillsafe.ai/
API tutorial: https://changelog-desk.skillsafe.ai/api.html
Derived from the agent skill @wshobson/changelog-automation (wshobson/agents, MIT):
https://skillsafe.ai/skill/@wshobson/changelog-automation

## What the browser does (free, no account)

- Parses the changelog: version headings (## [1.2.0] - 2026-05-01 and common variants such as
  "v1.2.0 (2026-05-01)"), the Unreleased section, the six change types (Added, Changed,
  Deprecated, Removed, Fixed, Security), entries, [YANKED] markers and link reference
  definitions (labels matched case-insensitively, as CommonMark does).
- Raises findings with a severity (error, warn, info): no Unreleased section or not at the top,
  versions that are not valid SemVer, duplicate versions, versions not newest first by SemVer
  precedence, dates missing, not YYYY-MM-DD, ambiguous, impossible or in the future, headings
  that are not one of the six types (with the type each common alias maps to), empty sections,
  entries outside a type, entries that read like raw commit subjects (a leading hash, a
  Conventional Commits prefix, a merge line), bracketed versions with no link definition,
  compare links that point at the wrong versions, removals or breaking changes in minor or
  patch releases, new or deprecated functionality in patch releases, and skipped versions.
- Applies the mechanical fixes on request: canonical type names, ISO dates, [YANKED], empty type
  headings, a missing Unreleased section, and version links when the file shows how it writes
  them. Everything else is left for the person or the review.
- Reads a commit log (git log, git log --oneline --decorate, one subject per line, or blocks
  separated by ---) under Conventional Commits 1.0.0: type, scope, ! and BREAKING CHANGE /
  BREAKING-CHANGE footers (uppercase only, as the spec requires), issue numbers, merge commits
  (left out), and reverts, which cancel the reverted commit when both are in the range. It
  stops at the first commit decorated with a version tag.
- Computes the next version: a breaking change is major, feat is minor, fix is patch, and every
  other type has no version effect (Conventional Commits 1.0.0). Increments follow node-semver's
  inc(), so 2.0.0-rc.1 plus a fix becomes 2.0.0. Before 1.0.0 two options mirror release-please's
  bump-minor-pre-major and bump-patch-for-minor-pre-major (both off by default). A pre-release
  identifier (rc, beta) gives 3.0.0-rc.0, then 3.0.0-rc.1.
- Inserts a release into the file under Unreleased, optionally moving the Unreleased entries into
  it, and updates the [Unreleased] and new version compare links in the file's own URL style.

## The paid lanes (one system prompt, routed on `task`)

- review: input { task: "review", facts: "<JSON string>", question? }. Reply: { lane, verdict
  (ready | fix_first | rework, never looser than the browser's floor), headline, findings
  [{flag, note}], rewrites [{entry, after, type, why}], missing [{release, type, note}], summary }.
- draft: input { task: "draft", facts: "<JSON string>", question? }. Reply: { lane, version
  (the browser's next version, exactly), headline, sections {Added, Changed, Deprecated, Removed,
  Fixed, Security: [{text, commits}]}, breaking [{commits, migration}], omitted [{commits, why}],
  version_note, questions, summary }.
- The page then checks the reply: every error and warning answered, the verdict no looser than
  the floor, every rewritten or drafted entry run through the same commit-subject detector, every
  user-facing commit placed or explained, every breaking commit given a migration note, and no
  commit id, issue number or version that the input does not carry.

## What it does not do

It never runs git and never reads a repository; it reads what is pasted. A clean check does not
mean the changelog is complete. Keep a Changelog and the pre-1.0 options are conventions, not
parts of the SemVer spec.

## Sources

- Keep a Changelog 1.1.0: https://keepachangelog.com/en/1.1.0/
- Semantic Versioning 2.0.0: https://semver.org/spec/v2.0.0.html
- Conventional Commits 1.0.0: https://www.conventionalcommits.org/en/v1.0.0/
- CommonMark 0.31.2, link reference definitions: https://spec.commonmark.org/0.31.2/#link-reference-definitions
- node-semver (increment semantics the page matches): https://github.com/npm/node-semver
- release-please manifest options: https://github.com/googleapis/release-please/blob/main/docs/manifest-releaser.md