Monorepo Release Notes for Multiple Packages

Monorepo Release Notes

Monorepos present unique challenges for release notes because multiple packages are often released simultaneously with interdependencies. The release notes need to be organized so users of individual packages can find relevant changes quickly.

Approach 1: Unified Release Notes

# Release 2026-02-28

## @projectx/core v3.1.0

### Added
- New event system with typed events (#1234)
- `onBeforeRender` lifecycle hook (#1236)

### Fixed
- Fix memory leak in effect cleanup (#1230)

## @projectx/router v2.5.0

### Added
- Nested route support with layout components (#1240)
- Route-level code splitting (#1242)

### Changed
- Requires @projectx/core >= 3.1.0

## @projectx/cli v4.0.0

### BREAKING CHANGES
> The `build` command now uses esbuild by default.
> To use webpack, add `--bundler webpack`.

### Added
- esbuild integration for 10x faster builds (#1250)

## Compatibility Matrix

| Package | Version | Requires |
|---------|---------|----------|
| @projectx/core | 3.1.0 | - |
| @projectx/router | 2.5.0 | core >= 3.1.0 |
| @projectx/cli | 4.0.0 | core >= 3.0.0 |
| @projectx/devtools | 2.0.0 | core >= 3.0.0 |

Approach 2: Per-Package with Cross-References

Some monorepos maintain separate CHANGELOGs per package with cross-references:

packages/
  core/
    CHANGELOG.md     # Core-specific changes
  router/
    CHANGELOG.md     # Router-specific changes
  cli/
    CHANGELOG.md     # CLI-specific changes
CHANGELOG.md         # Umbrella changelog linking to all

Tools for Monorepo Releases

• Lerna: lerna version + lerna publish with changelog generation
• Changesets: PR-based changelog entries, ideal for collaborative monorepos
• Turborepo + semantic-release: Automated per-package releases

Best Practices

1. Always include a compatibility matrix showing which versions work together
2. Note cross-package dependencies when a change in one package requires a specific version of another
3. Order packages by dependency depth (core packages first)
4. Use consistent version dates across all packages in a coordinated release
5. Provide a single upgrade command when possible: npm install @projectx/core@latest @projectx/router@latest