LogPulse / guides

How to keep a changelog in a monorepo

In a monorepo the first question is scope: one changelog for the repository, or one per package? Below: a copy-paste per-package CHANGELOG.md, how Changesets, Nx and release-please tag releases, four real monorepos to copy, and how to draft one package's entry from git.

Updated Last checked 8 min readOpen-source libraries and packages

Copy-paste changelog for one package in a monorepo

A per-package entry in Keep a Changelog 2.0.0 format for packages that version independently. It sits next to the package's manifest, says which sibling package it shipped with, and links compare views between this package's own tags.

packages/sdk/CHANGELOG.md
# Changelog: acme-sdk

All notable changes to acme-sdk are documented in this file. Other packages in
this repository keep their own changelog next to their package.json.

## [Unreleased]

## [2.0.0] - YYYY-MM-DD

One breaking change: `createClient()` needs an `apiKey`. Released together
with acme-core 3.0.0.

### Added
- `retry` option on `createClient()` for idempotent requests ([#981]).

### Changed
- **Breaking:** `createClient()` throws without an `apiKey`. Pass it explicitly
  or set the `ACME_API_KEY` environment variable.
- Updated dependencies: acme-core 3.0.0 (see packages/core/CHANGELOG.md).

### Fixed
- Requests time out after `timeout` milliseconds again ([#975]).

[Unreleased]: https://github.com/OWNER/REPO/compare/acme-sdk@2.0.0...HEAD
[2.0.0]: https://github.com/OWNER/REPO/compare/acme-sdk@1.4.2...acme-sdk@2.0.0
[#975]: https://github.com/OWNER/REPO/pull/975
[#981]: https://github.com/OWNER/REPO/pull/981

Package names, versions and pull request numbers are placeholders. If acme-core's break reaches acme-sdk's users (say, through a re-exported type), mark it breaking here too.

The short answer

  • Packages with their own version numbers get their own CHANGELOG.md next to their manifest. If they make up one product, Keep a Changelog 2.0.0 also asks for a short central changelog that sums up each release.
  • Packages that always ship together can share one version and one root changelog. Start each line with the package it touches, as Jest does: [jest-config] ….
  • Tag each release with the package's name, such as acme-sdk@2.0.0 (Changesets, Nx) or acme-sdk-v2.0.0 (release-please), so tools find the previous release of the same package.
  • When a package is released only because an internal dependency changed, say which dependency and version, as Changesets' ‘Updated dependencies’ lines do.
  • Put a breaking change in the changelog of every package whose users must act, not only the package where the code changed.
  • To draft one package's entry, limit git to its folder: git log acme-sdk@1.4.2..HEAD -- packages/sdk.

Free GitHub Action · no sign-up

Publish each package's entry as its GitHub release

The free LogPulse GitHub Action reads package tags like acme-sdk@2.0.0 or acme-sdk-v2.0.0, finds that package's previous tag and copies the matching section of the CHANGELOG.md you point it at into the release. No account, and it never calls LogPulse.

.github/workflows/release-notes.yml
name: Release notes

on:
  release:
    types: [published]

permissions:
  contents: write

jobs:
  notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: kalmwerk/release-notes-action@v1

On GitHub now; Marketplace listing coming soon: releases. Rather keep a copy in your repository? Download 1.0.4 (29 KB). On GitLab? Use the CI/CD component

No CHANGELOG.md yet? See the notes your merged pull requests give first: generate release notes from GitHub, free and with nothing to install.

Free tool · no sign-up

Can a coding agent read your changelog?

Paste your repository, a GitHub release or a CHANGELOG.md link. The free converter shows every version, breaking change, migration step and deprecation it can extract, as JSON plus an llms.txt summary.

No AI, and your changelog isn't stored. Or paste a CHANGELOG.md instead

01One changelog or one per package?

Decide by how the packages are versioned, not by how the repository is laid out. The tools give the two modes different names, but the split is the same.

How packages are versionedTool names for itChangelog
All packages always share one versionChangesets fixed, Nx fixed releases, Lerna fixed modeOne root CHANGELOG.md; start each line with the package name
Packages are versioned on their ownChangesets (default), Nx projectsRelationship: "independent", release-please with several packages, Lerna independent modeOne CHANGELOG.md per package, next to its manifest, plus a short central summary if the packages are one product
Groups that share a version, others on their ownChangesets linked or fixed groups, Nx release groups, release-please linked-versionsOne changelog per group or per package; say in each entry which packages shipped together

Changesets' docs describe fixed packages as ones where “all packages will always have the same version”: they're bumped and published together even when some have no changes. Linked packages share a version number but only those with changes are released. Changesets, Nx in independent mode and release-please all write one changelog per package.

Keep a Changelog 2.0.0 draws the line by product, not by tool. Unrelated projects that share a repository each keep their own changelog. A single product made of many parts “can keep a changelog per component, but should also keep one central changelog”, because “readers should not have to read a dozen component changelogs to understand what a release means.” Nx “will no longer generate and update a workspace level CHANGELOG.md file when configured for independent releases”, so that summary is yours to write: a few lines per release that link the package entries. Either way, list every package's CHANGELOG.md in the README.

CHANGELOG.md (one shared version, Jest-style package prefixes)
# Changelog

## [30.0.0] - YYYY-MM-DD

### Added
- `[acme-cli]` `acme init --template` picks a starter template.

### Changed
- **Breaking:** `[acme-config]` `rootDir` must be set. Add `rootDir: "."` to keep
  the old behaviour.

### Fixed
- `[acme-cli, acme-core]` Paths with spaces work on Windows again.

[30.0.0]: https://github.com/OWNER/REPO/compare/v29.4.0...v30.0.0

02Tag every package release with the package's name

A plain v2.0.0 tag can't say which package it belongs to. Tools that work out ‘what changed since the last release’ look for the previous tag of the same package, so the package name has to be in it.

ToolDefault tag for a package releaseWhere it's set
Changesetspkg-name@X.X.X (a single-package repository gets vX.X.X)Its versioning and publishing docs
Nx (independent){projectName}@{version}, e.g. pkg-1@1.1.0release.releaseTag.pattern in nx.json (Nx 22+)
release-please (manifest)<component>-v<release-version>include-component-in-tag: false gives plain v<version>
cargo-release (Rust workspace){{crate_name}}-v{{version}} for crates outside the repository roottag-prefix in release.toml

Keep one format per repository, and use the same name in the tag, the changelog's compare links and the GitHub release title. Vite shows the mixed case: the main package uses v8.x tags and the other packages, such as create-vite, use create-vite@9.3.4, each with its own CHANGELOG.md under packages/.

03Write down internal dependency bumps

In a monorepo, a fix in one package often releases several others that depend on it. Their changelogs should say why they have a new version, or readers see an empty entry and wonder.

  • List the internal dependency and the version you moved to: “Updated dependencies: acme-core 3.0.0.” Changesets writes these lines for you, with the commit links.
  • Link the dependency's own changelog instead of copying its entries.
  • If the dependency's change reaches this package's users, write it as this package's change too. A breaking change in a re-exported type is a breaking change for every package that re-exports it.
  • For a Rust workspace, Python namespace packages or a Go multi-module repository, the same rules apply with Cargo.toml, pyproject.toml or go.mod in place of package.json. See the Rust crate, npm and PyPI guides for the registry details.

04Set up the tool you use

Each tool writes per-package changelogs from a small piece of config. These are the minimal settings; check each tool's docs for the rest.

.changeset/config.json (two packages that always share a version)
{
  "fixed": [["acme-sdk", "acme-core"]]
}
nx.json (independent versions, one changelog per project)
{
  "release": {
    "projectsRelationship": "independent",
    "changelog": {
      "projectChangelogs": true
    }
  }
}
release-please-config.json (changelog defaults to CHANGELOG.md in each package)
{
  "release-type": "node",
  "packages": {
    "packages/sdk": { "component": "acme-sdk" },
    "packages/core": { "component": "acme-core" }
  }
}

release-please also needs a .release-please-manifest.json with each package's current version, such as {"packages/sdk": "1.4.2"}. How the three tools compare on everything else is in semantic-release vs release-please vs Changesets.

05Common monorepo changelog mistakes

Each of these makes readers dig through changes that aren't theirs, or miss one that is.

  • One root changelog for independently versioned packages. Someone upgrading acme-sdk to 2.0.0 has to read past every acme-cli entry to find theirs.
  • Plain v2.0.0 tags in a multi-package repository. Tools can't tell which package's previous release to compare against.
  • Empty entries for dependency-only releases. Write “Updated dependencies: acme-core 3.0.0” so readers know why there's a new version.
  • A breaking change in one package's changelog only, when a re-export carries it into others.
  • Compare links between whole-repository tags, which pull in every other package's commits.
  • Drafting from the whole repository's git log. Other packages' commits end up in this package's entry; add -- packages/sdk.

06Generate one package's entry from your commits

No release tool yet, or you want a draft to edit before it ships? Limit git to the package's folder and the range since its last tag. Git's pathspec (-- <path>) keeps only the commits that touched those files.

Commits for one package since its last release
# acme-sdk since its last tag, only commits that touched packages/sdk
git log acme-sdk@1.4.2..HEAD --no-merges -- packages/sdk

# Same, for a package that shares a version with the rest of the repository
git log v29.4.0..HEAD --no-merges -- packages/config
  1. Paste the output into the free changelog from commits tool. It sorts Conventional Commits into Added, Changed and Fixed and flags feat!: and BREAKING CHANGE: as breaking, naming the scope each break affects (feat(sdk)!: becomes a breaking line for sdk).
  2. Edit the draft: add the internal dependency lines, merge related commits, and add a replacement to every breaking change.
  3. Paste it under the new version in the package's CHANGELOG.md, then let the GitHub Action publish it as the release when you push the package's tag. Point its changelog-path at the package's file and set source: changelog, because its commit fallback reads the whole repository, not one folder.

git-cliff can do the same filtering from the command line with --include-path, and the generate a changelog from git guide has more git log recipes.

Real projects that do this well

Public release notes worth copying from. Each link opens the project's own page.

Before and after

Too vague

Release 2026-11-16: bumped 7 packages, various fixes.

Specific and actionable

acme-sdk 2.0.0 (breaking): createClient() throws without an apiKey; pass it or set ACME_API_KEY. Released with acme-core 3.0.0. acme-cli 1.8.1: updated dependencies (acme-core 3.0.0), no other changes.

Fictional example: use your own verified names, versions and behavior.

LogPulse

Generate release notes with LogPulse

LogPulse is a hosted changelog that people and coding agents can both read. Here's exactly what it can do for the steps above, and what it can't.

  1. Check your changelog, free

    Paste a CHANGELOG.md or a GitHub releases link. A deterministic parser (no AI; your changelog isn't stored) shows the versions, breaking changes, migration steps and deprecations an agent can extract.

    Open the converter

  2. Draft notes from GitHub

    Connect a repository: merged pull requests, commits to your default branch and published GitHub releases collect in an inbox. AI drafts a note in the tone you pick, listing breaking changes and deprecations only when the changes clearly show them. Nothing is published until you approve it. 3 AI drafts on Free; unlimited on Open source and Pro. Pro opens soon: .

    Free for open source

  3. Publish once, read everywhere

    Approved notes go to a hosted changelog and an in-app widget, to email subscribers on Open source and Pro (Pro opens soon), and to a JSON feed and MCP server coding agents can query. CI and agents can publish with an API key.

    Read the docs

What it doesn't do: LogPulse doesn't tag releases, bump versions, publish to npm or PyPI, or write CHANGELOG.md back to your repository; keep your release tooling for those. AI drafts can miss context, so review them like a pull request.

Before you publish

  • Each independently versioned package has its own CHANGELOG.md next to its manifest
  • The README links to every package's changelog
  • Tags include the package name, in one format for the whole repository
  • Compare links use that package's own tags
  • Internal dependency bumps say which package and version
  • Breaking changes appear in every package whose users must act

Common questions

Should a monorepo have a CHANGELOG.md at the root?

If all packages share one version, yes: that's the changelog, with the package name at the start of each line. If packages are versioned on their own but make up one product, Keep a Changelog 2.0.0 says to keep a central changelog as the summary next to the per-package ones. Unrelated projects in one repository only need their own.

How do I get the commits for one package?

Use git's pathspec with the package's last tag: git log acme-sdk@1.4.2..HEAD --no-merges -- packages/sdk. Only commits that touched files in that folder are listed.

What tag format should packages in a monorepo use?

One that includes the package name. Changesets and Nx default to name@version (acme-sdk@2.0.0) and release-please to name-v-version (acme-sdk-v2.0.0). Pick one and use it for every package.

Sources

Facts last checked against these sources on .

Next step

Automate this on every release

Skip the copy-paste next time: let your pipeline write the release notes when you tag. Free, no LogPulse account.

  • GitHub ActionWrites each GitHub release from CHANGELOG.md or the pull requests merged since the last tag.Set it up
  • GitLab componentThe same notes for GitLab releases, in a tag pipeline. Only needs CI_JOB_TOKEN.Set it up
  • Free API & MCPRelease notes, changelog checks and conversion over HTTP or MCP. No key, no account.Read the docs
  • A draft from every merged pull request, published to your widget, hosted changelog and subscribers' inboxes.€12/month or €99/year + VAT · opens soonJoin the waitlist

More guides: open-source libraries and packages

All release notes guides

Tools and resources

LogPulse

Changelogs coding agents can upgrade from.

Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.