Skip to content

docs(changelog): clean up changelog - #1744

Merged
pranavosu merged 3 commits into
mainfrom
docs/concise-1.0.0-changelog
Nov 20, 2026
Merged

pranavosu merged 3 commits into
mainfrom
docs/concise-1.0.0-changelog

Conversation

@pranavosu

@pranavosu pranavosu commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

The 1.0.0 release (#1738) added 10,177 lines to the 27 package changelogs. Leaving pre mode makes changesets copy every rc entry into the 1.0.0 section, so each 1.0.0 section repeated its 1.0.0-rc.* sections, plus about 3,400 "Updated dependencies" lines. The older sections have the same two problems: one long changeset is copied into every package it names, and a dependency list sits under every version. A reader who upgrades from 0.x can't find what they need, and three of the 1.0.0 GitHub Releases failed to create.

Issue #, if available: none

Changes

The 27 changelogs go from 36,517 lines to 5,607.

Each package's ## 1.0.0 section now has:

  1. A short intro that points to the package's own rc sections.
  2. "Changes since @aws-blocks/<pkg> 0.x": the rename, then one line for each breaking change or new feature (the changelog's minor entries), with its commit hash. admin-ui, bb-auth and bb-database had no stable release under the old name, so their first line says what they replace. create-blocks-app and create-block give the command to run in place of the old one.
  3. "Since 1.0.0-rc.2" (rc.1 for packages whose last rc was rc.1): the naming change, 63e571c.

Every other section:

  • Each entry is one or two sentences that say what changed and what you have to do. The text was written once for each of the 771 unique entries and applied to every package that carries the entry.
  • A breaking change keeps a bold one-line summary and its numbered upgrade steps, with the exact commands. There are 50 of them.
  • The "Updated dependencies" items are removed. A version that had nothing else says "Dependency updates only."
  • The full text of every entry stays in git history, at chore: version packages #1738.

Titles: each changelog's title is the current package name. 24 of them still had the @aws-blocks/… name.

scripts/changeset-guard.ts: verify-coverage no longer counts a change to packages/<pkg>/CHANGELOG.md alone. Correcting the notes of a release that already shipped shouldn't need a changeset, and so a new release. A CHANGELOG edit that comes with any other change to the package still needs a changeset. This changes the release policy, so please review it separately.

Changeset: aws-cdk-blocks ships every package's CHANGELOG.md in docs/, so this PR changes its package content. A patch changeset for aws-cdk-blocks covers that, and Blocks Package Integrity passes with it.

Validation

  • scripts/changeset-guard.test.mjs has two new tests:
    • A CHANGELOG-only edit passes with no changeset. It failed before the guard change.
    • A CHANGELOG edit with a code change still needs one.
  • node --test scripts/changeset-guard.test.mjs passes.
  • verify-coverage on this PR reports "No publishable packages were changed". validate-structure, verify-umbrella, block-major and npm run check:dot-folder pass.
  • A script checked every rewritten entry against its original: each name in code font and each number appears in the original, and no entry was dropped. All 50 breaking entries and a sample of 45 others were also read against their originals.

Checklist

  • PR description included
  • Tests are changed or added
  • Relevant documentation is changed or added (and PR referenced)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

Each package's 1.0.0 section repeated every rc entry and a list of
dependency bumps. It now has the package rename, one line for each
breaking change or new feature since 0.x, and the changes since the
package's last rc. The rc sections keep the full notes.

The changeset coverage check no longer counts an edit to a package's
CHANGELOG.md alone, so correcting the notes of a shipped release does
not need a new release.
@pranavosu
pranavosu requested a review from a team as a code owner November 20, 2026 22:14
svidgen
svidgen previously approved these changes Nov 20, 2026
aws-cdk-blocks ships every package's CHANGELOG.md in docs/, so the
shorter changelogs change its package content.

This branch was previously deployed

2 inactive deployments
e2e — 367ed6f4 Deployed Nov 21, 2026 by pranavosu via E2E Teardown Verify #7844
agent-bench — 367ed6f4 Deployed Nov 21, 2026 by pranavosu via bench / summary #6851
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants