Update release docs and workflow (#2718)

* Update release docs and workflow

* Fix typos

* Revise based on watching Patrick complete the release

Co-authored-by: Patrick Brosset <[email protected]>

* Fix admonition (hopefully)

* Fix admonition formatting

---------

Co-authored-by: Patrick Brosset <[email protected]>

Author: ddbeck

.github/workflows/bcd_upgrade_checklist.yml

@@ -21,6 +21,8 @@ jobs:
         uses: peter-evans/create-or-update-comment@71345be0265236311c031f5c7866368bd1eff043 #v4.0.0
         with:
           issue-number: ${{ github.event.number }}
+          # TODO: reinstate this post-merge checklist item when https://github.com/web-platform-dx/web-features/issues/1672 is resolved
+          # - [ ] (Optional) [Trigger a workflow run to remove tagged compat features](https://github.com/web-platform-dx/web-features/actions/workflows/remove_tagged_compat_features.yml).
           body: |
             Complete this checklist for every `@mdn/browser-compat-data` upgrade PR.
 
@@ -33,5 +35,4 @@ jobs:
             After merging, do these steps:
 
             - [ ] [Trigger a drafts update workflow run](https://github.com/web-platform-dx/web-features/actions/workflows/update_draft_features_weekly.yml).
-            - [ ] (Optional) [Trigger a workflow run to remove tagged compat features](https://github.com/web-platform-dx/web-features/actions/workflows/remove_tagged_compat_features.yml).
             - [ ] Start a PR to [publish the next web-features release](https://github.com/web-platform-dx/web-features/blob/main/docs/publishing.md#regular-releases).

docs/publishing.md

@@ -20,20 +20,38 @@ Announcements should not provoke surprising responses from consumers.
 > [!NOTE]
 > This section is for [project owners](../GOVERNANCE.md#roles-and-responsibilities).
 
-These are the steps to publish a regular release on npm and as a GitHub release:
+These are the steps to publish a regular release on npm and as a GitHub release.
+Typically, a maintainer follows these steps shortly after merging a Dependabot PR that upgrades `@mdn/browser-compat-data`.
+
+> [!TIP]
+> 
+> Running the stats for the `main` branch and previous release can help you determine the next release's version number and writing the release notes.
+> Run these commands to get stats for the previous release:
+> 
+> ```sh
+> $ PREVIOUS_RELEASE_TAG=$(gh release view --json tagName --jq .tagName)
+> $ git fetch --tags && git checkout "$PREVIOUS_RELEASE_TAG" && npm install && npx tsx ./scripts/stats.ts
+> ```
+> Run these commands to get stats for the `main` branch:
+> 
+> ```sh
+> $ git fetch origin main && git checkout origin/main && npm install && npx tsx ./scripts/stats.ts
+> ```
+
+To publish a release:
 
 1. Determine if it should be a major, minor, or patch release.
 
    A major version is required for releases when:
 
-   - Previously valid references are invalid (for example, a group ID is renamed or a feature ID is removed).
-   - Types have incompatibly narrowed, widened, or otherwise changed (for example, a string value now accepts an array of strings or an ID has become a URL). Changes to `data.schema.json` often indicates a major or minor version is required.
+   - The schema changes such that types have incompatibly narrowed, widened, or otherwise changed (for example, a string value now accepts an array of strings or an ID has become a URL). Changes to `data.schema.json` often indicates a major or minor version is required.
+   - A group or feature ID is removed, or any other previously valid references becomes undefined.
 
-   A minor version is required for releases that contain only additions, such as new feature or new properties on existing types.
+   A minor version is required for releases that contain only additions, such as new features or new properties on existing types.
 
    Patch versions are required for releases that contain only routine data changes, such as updates to `compat_features` arrays or `support` objects.
 
-   The "[major version required][major-version]" and "[minor version required][minor-version]" labels should be used to support this decision.
+   Check "[major version required][major-version]" and "[minor version required][minor-version]" labels for pull requests or issues that require versioning.
 
 1. Trigger the [Prepare web-features release workflow](https://github.com/web-platform-dx/web-features/actions/workflows/prepare_release.yml).
 
@@ -48,12 +66,18 @@ These are the steps to publish a regular release on npm and as a GitHub release:
    1. Close and reopen the release PR, to allow the tests to run.
    1. Review and approve the changes.
    1. When you're ready to complete the remaining steps, merge the PR.
+      To avoid re-doing release prep (such as having to change the semver level), don't delay any of the remaining steps after merging.
 
 1. Create the GitHub release.
 
    1. Go to https://github.com/web-platform-dx/web-features/releases/new to start a new draft release.
-   1. Fill in the tag name `vX.Y.Z` manually as both the tag and release title.
+   1. Create a new tag in the pattern `vX.Y.Z`.
+   1. Fill in the release title `vX.Y.Z`.
    1. For minor releases, add a `## What's New` section to the top of the release notes, before all other sections.
+
+      1. In this section, add a line `* X features`, where `X` is the number of features new in this release.
+      1. In this section, add a line `* Y% coverage of BCD`, where `Y` is the coverage percentage for this release.
+
    1. For major releases, add a `## Breaking Changes` section to the top of the release notes, before all other sections.
    1. Click **Generate release notes**.
    1. In the release description, find unescaped `<` characters and make sure that HTML elements are enclosed with backticks.
@@ -64,7 +88,12 @@ These are the steps to publish a regular release on npm and as a GitHub release:
       / (?<!`)<(.*?)> /
       ```
 
-   1. Remove all lines from Dependabot.
+   1. Remove all generated lines for:
+   
+      - `Update draft features by @github-actions`
+      - Dependabot PRs except `@mdn/browser-compat-data` upgrades
+      - `📦 Release web-features`
+
    1. Append this message to the end of the release notes:
 
       ```markdown
@@ -79,6 +108,10 @@ These are the steps to publish a regular release on npm and as a GitHub release:
 
 1. (_Optional_) If this release contained schema changes, notify highly-visible downstream consumers, such as Can I Use (@Fyrd), MDN (@LeoMcA), or webstatus.dev (@jcscottiii).
 
+1. Post a message to the WebDX Matrix chat to announce the release.
+
+Congratulations, you've released web-features. 🎉
+
 [major-version]: https://github.com/web-platform-dx/web-features/pulls?q=is%3Apr+is%3Amerged+label%3A%22major+version+required%22+sort%3Aupdated-desc
 [minor-version]: https://github.com/web-platform-dx/web-features/pulls?q=is%3Apr+is%3Amerged+label%3A%22minor+version+required%22+sort%3Aupdated-desc