docs, ci: add spec and package changelogs with a CI check

.github/workflows/changelog.yml

@@ -0,0 +1,37 @@
+name: Changelog
+on:
+  pull_request:
+    # labeled and unlabeled re-run this workflow when the
+    # "changelog: skip" label is applied or removed. Actions cannot
+    # filter those events by label name, so the changelog check lives
+    # here rather than in ci.yml, where every label change would
+    # re-run the whole suite.
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  contents: read
+
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    if: >-
+      ${{ !contains(github.event.pull_request.labels.*.name,
+      'changelog: skip') }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+          cache-dependency-path: yarn.lock
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Check changelogs are updated
+        run: >-
+          yarn tsx bin/check-changelog.ts
+          "origin/${{ github.base_ref || 'main' }}"

RELEASING.md

@@ -43,7 +43,53 @@ guards that run in CI live in `bin/check-tarballs.ts` and
    yarn lerna list --all --json
    ```
 
-3. Bump to an explicit version. Lerna commits the result as
+3. Update the changelogs before bumping. The root `CHANGELOG.md`
+   tracks the spec version; each public package under
+   `packages/*/CHANGELOG.md` tracks that package's own version.
+
+   See which packages the next step will move:
+
+   ```console
+   yarn lerna changed
+   ```
+
+   The bump in step 4 moves every package that command lists, plus
+   every package that depends on one of them.
+
+   For the root file, and for each package about to be bumped,
+   rename its `## Unreleased` heading to
+   `## <version> — <YYYY-MM-DD>`: that package's own new version,
+   then today's date. Leave a fresh, empty `## Unreleased` heading
+   above the section you renamed. A package that is not being bumped
+   needs no change.
+
+   When you rename `## Unreleased` in the root file, reconcile its
+   entries against the previous published version. Each `Producers:`
+   and `Consumers:` line states the net effect for a party that
+   moves from that version to the new one. If one Unreleased entry
+   reverses an obligation of another Unreleased entry, neither
+   impact line keeps that obligation; the summaries may still tell
+   the history.
+
+   A package that is bumped only because a dependency of it changed
+   has nothing under `## Unreleased`. Give it a `### Changed` entry
+   reading "Updated `@ethdebug/<dep>` to `<version>`.", so that every
+   published version has a section of its own.
+
+   Commit the renamed files on their own, right before the version
+   bump in the next step:
+
+   ```console
+   git add CHANGELOG.md packages/*/CHANGELOG.md
+   git commit -m "docs: cut changelog entries for <version>"
+   ```
+
+   Pre-flight check: in each file you touched, the only remaining
+   `## Unreleased` section is the empty one at the top. Never publish
+   with entries still sitting under `## Unreleased` in a changelog
+   for a package (or the spec) being released.
+
+4. Bump to an explicit version. Lerna commits the result as
    `Publish` and creates one tag per bumped workspace on that
    commit:
 
@@ -62,22 +108,22 @@ guards that run in CI live in `bin/check-tarballs.ts` and
    - `--no-push`: Lerna would otherwise run
      `git push --follow-tags --no-verify --atomic <remote> <branch>`
      and, when the error text mentions "atomic", silently retry
-     WITHOUT `--atomic`. The push happens by hand in step 5 instead:
+     WITHOUT `--atomic`. The push happens by hand in step 6 instead:
      no non-atomic fallback, no `--no-verify` skipping the pre-push
-     hooks, and step 4's inspection happens before anything reaches
+     hooks, and step 5's inspection happens before anything reaches
      the remote.
    - `--yes`: skips the confirmation prompt. Preview with the command
      in step 2 first; do not use `--no-git-tag-version` as a
      preview, because it still rewrites every `package.json`.
 
-4. Inspect the result before pushing:
+5. Inspect the result before pushing:
 
    ```console
    git show --stat HEAD
    git tag --points-at HEAD   # expect one tag per bumped workspace
    ```
 
-5. Push the commit and the tags in one atomic operation:
+6. Push the commit and the tags in one atomic operation:
 
    ```console
    git push --atomic origin main --follow-tags
@@ -110,7 +156,7 @@ guards that run in CI live in `bin/check-tarballs.ts` and
    git push origin :refs/tags/<tag>
    ```
 
-6. Watch the workflow and confirm the result on the registry:
+7. Watch the workflow and confirm the result on the registry:
 
    ```console
    gh run list --workflow publish.yml --limit 3
@@ -240,10 +286,12 @@ GitHub Actions the script does not pass `--provenance`.
 - `bin/check-tarballs.ts` (CI, `run-tests` job) lists the files that
   `npm pack` would put in each public package's tarball and fails if
   any file lies outside `package.json`, `README*`, `LICENSE*`,
-  `dist/src/` or `dist/bin/`, or if any `.test.` or `.tsbuildinfo`
-  file is included. It catches a wrong `files` field, test files
-  leaking into the package, and stale build output. The publish
-  script runs the same check before every publish.
+  `CHANGELOG*`, `dist/src/` or `dist/bin/`, or if any `.test.` or
+  `.tsbuildinfo` file is included. It catches a wrong `files` field,
+  test files leaking into the package, and stale build output. The
+  publish script runs the same check before every publish. npm ships
+  `package.json`, `README*` and `LICENSE*` whatever `files` says, but
+  not `CHANGELOG.md`, so every public package lists it in `files`.
 - `bin/smoke-tarballs.ts` (CI, `run-tests` job) packs every public
   package, installs each tarball into a throwaway consumer project
   together with the tarballs of its sibling dependencies, imports