Monorepo changelogs: one changelog or many?

A monorepo breaks the comfortable assumption that one repository equals one changelog. Suddenly there are twelve packages, three deployable apps, and a shared design system in one tree — and a single CHANGELOG.md at the root stops making sense. This guide covers where changelogs should live in a monorepo, what the popular tooling actually does, and the aggregation problem everyone hits six months in.

The rule: changelogs follow release units, not repositories

A changelog documents a thing people consume. So count your independently consumed things, and that's how many changelogs you need:

  • Packages that version and publish independently (npm workspace packages, Go modules, crates) → one changelog per package. A user of @acme/auth should not have to read about @acme/charts to learn what changed under them.
  • A product that ships as one unit — even from a monorepo of 40 internal packages → one changelog. Your users experience one product; internal package boundaries are your business, not theirs.
  • Both at once — a platform with published SDKs and a hosted app — → per-package changelogs for the SDKs, plus one product-level stream. More on the layering below.

The repository layout is irrelevant to all of this. That's the whole trick: stop asking "where does the file go in the repo" and ask "who upgrades what".

What the tooling actually does

The mainstream monorepo release tools all converged on per-package changelogs:

  • Changesets (the de-facto standard in JS monorepos) has contributors write a small "changeset" file at PR time — affected packages, bump type, and a human sentence about the change. At release, it aggregates pending changesets into each package's CHANGELOG.md and bumps versions, including cascading bumps for internal dependents. Its core insight is worth stealing even without the tool: capture the human description while the author still remembers why, not at release time.
  • release-please in manifest mode maintains per-package versions and changelogs from Conventional Commits, using commit scopes and paths to route entries to the right package.
  • Lerna (older JS monorepos) generates per-package changelogs from commits in each package's directory.

All three produce drafts. The curation rule from our git-commits guide applies double in monorepos: auto-routed entries are written in internal vocabulary ("bump @acme/core to 4.1") that means nothing to the people reading the changelog.

The aggregation problem

Per-package changelogs are correct for consumers of packages — and useless for everyone else. Six months in, someone asks "what did we actually ship this quarter?" and the answer is scattered across fourteen files, most entries reading "fix: internal refactor". Meanwhile your actual customers follow none of those files, because nobody subscribes to fourteen changelogs.

The fix is layering, not merging:

  • Per-package changelogs stay mechanical. Compatibility records for programmers: versions, breaking changes, migration notes. Generated + curated.
  • One product-level stream carries the story. Human-written, dated entries about outcomes: "SDK v5: token refresh is now automatic". It links down to package changelogs for details. This is the page you put in front of customers, the one with the visible heartbeat.

The two layers have different audiences, different vocabularies, and different cadences — which is exactly why one merged document serves neither.

Anti-patterns

  • One root CHANGELOG.md for twelve packages. Every entry needs a package prefix, nobody can filter, and consumers of one package wade through eleven others' noise. This is the default failure mode of "we'll just keep it simple".
  • Publishing the commit stream. Auto-generating from a busy monorepo's commits without curation produces hundreds of "chore(deps)" lines. A changelog nobody can read is a changelog nobody reads.
  • Internal names in the product stream. "Bumped @acme/design-tokens to 3.0" is not a product update. If a change isn't visible to users, it doesn't belong in the product layer — that's what package changelogs are for.
  • Cross-package breaking changes announced once. If upgrading @acme/auth forces a @acme/client upgrade, say so in both changelogs. Consumers read the one they depend on, not your dependency graph. (Breaking-change playbook here.)

Practical setup

# Per-package: let the tool do the bookkeeping
npx changeset          # contributor describes the change at PR time
npx changeset version  # release: writes per-package CHANGELOGs + bumps

# Product layer: one human entry per meaningful ship, posted from CI

The product layer is deliberately low-tech: when something user-visible ships, someone writes two honest sentences. The discipline is editorial, not technical — the same rules as any changelog: outcomes not diffs, dates, tags, name the pain when fixing.

Where Wakelog fits

Wakelog's account model maps onto the layering directly: projects are free, so you can run one project per published package (each with its own public page, RSS feed, and README badge) plus a product-level project for the human stream. Each CI job posts to its own project with one curl or the CLI — a matrix release job just sets a different project slug per package. Existing per-package CHANGELOG.md files import in one paste each, and everything exports back to plain markdown anytime.

Start a free changelog   Preview your CHANGELOG.md — no signup

Related guides

Last updated 2026-07-26 · All guides