diff --git a/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md b/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md index ff838bf31..0862d2fd0 100644 --- a/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md +++ b/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md @@ -4,15 +4,48 @@ Every release is announced in the **Announcements** category of [GitHub Discussions](https://github.com/microsoft/vscode-documentdb/discussions). The body always comes from `docs/release-notes/X.Y.md`, so write and commit the release notes first. -| Version type | What to post | Title | -| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -| Major or minor (X.Y.0) | One new discussion with the whole release notes file | `DocumentDB extension for Visual Studio Code vX.Y Released! ` | -| Patch (X.Y.Z, Z > 0) | 1. A new discussion with the patch section
2. Then the same text as a comment on the X.Y.0 announcement, in that order | `Patch Release vX.Y.Z 📎` (the 📎 emoji is part of the title) | +| Version type | What to post | Title | +| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | +| Major or minor (X.Y.0) | One discussion with the whole release notes file, reusing a confirmed placeholder if present | `DocumentDB extension for Visual Studio Code vX.Y Released! ` | +| Patch (X.Y.Z, Z > 0) | 1. Create or update the dedicated patch discussion
2. Then post the same text as a comment on the X.Y.0 announcement | `Patch Release vX.Y.Z 📎` (the 📎 emoji is part of the title) | + +## Ask about a placeholder before publishing + +Always ask the operator: **Is there already a placeholder discussion for this release? If so, what +is its URL?** If the request already includes a placeholder URL, ask for confirmation that it is the +one to update instead of asking for the URL again. Wait for the answer before publishing. Create a +new discussion only after the operator confirms there is no placeholder. + +When a placeholder is confirmed, read it and verify that it belongs to this repository's +**Announcements** category and is intended for this release. Ask the operator to resolve any +mismatch before editing. Update that discussion's title and body instead of creating another one. +For a patch, the placeholder must be the dedicated patch discussion, not the parent X.Y.0 +announcement; the parent still receives a comment afterward. + +Read the discussion using its number from the supplied URL, then use the returned node `id` to +update it with the title and prepared body from the applicable workflow below: + +```bash +gh api graphql -f query=' +query($number: Int!) { + repository(owner: "microsoft", name: "vscode-documentdb") { + discussion(number: $number) { id title url body category { name } } + } +}' -F number= --jq '.data.repository.discussion' + +gh api graphql -f query=' +mutation($id: ID!, $title: String!, $body: String!) { + updateDiscussion(input: {discussionId: $id, title: $title, body: $body}) { + discussion { url } + } +}' -f id= -f title='' -F body=@body.md \ + --jq '.data.updateDiscussion.discussion.url' +``` ## Patch release: post, then comment The order matters. Discussions sorts Announcements by most recent activity, so the X.Y.0 announcement -must receive its comment **after** the patch discussion is created. That keeps the main release +must receive its comment **after** the patch discussion is created or updated. That keeps the main release announcement on top, with the patch post right below it. 1. **Extract the patch section** from the release notes. It starts at `## Patch Release vX.Y.Z` and @@ -22,7 +55,9 @@ announcement on top, with the patch post right below it. awk '/^## Patch Release vX.Y.Z$/{p=1} p&&/^---$/{exit} p' docs/release-notes/X.Y.md > patch-body.md ``` -2. **Create the patch discussion** in Announcements, titled `Patch Release vX.Y.Z 📎`: +2. **Publish the patch discussion** in Announcements, titled `Patch Release vX.Y.Z 📎`. Update a + confirmed placeholder using the command above with `patch-body.md`; otherwise, after the + operator confirms there is no placeholder, create it: ```bash gh api graphql -f query=' @@ -84,7 +119,8 @@ announcement on top, with the patch post right below it. ## Major or minor release -1. Create the discussion in Announcements with the release notes body (everything after the front +1. Update the confirmed placeholder, or create the discussion only after the operator confirms + there is no placeholder. Publish in Announcements with the release notes body (everything after the front matter, `sed '1,/^---$/d' docs/release-notes/X.Y.md`, read with `-F body=@file`), titled `DocumentDB extension for Visual Studio Code vX.Y Released! `. Pick one emoji that fits the release. diff --git a/.github/skills/writing-release-notes/SKILL.md b/.github/skills/writing-release-notes/SKILL.md index 599c9ec07..036ebb41c 100644 --- a/.github/skills/writing-release-notes/SKILL.md +++ b/.github/skills/writing-release-notes/SKILL.md @@ -110,10 +110,17 @@ Version X.Y.Z: Once the release notes are committed, post the announcement in the **Announcements** category. Follow [ANNOUNCING-ON-DISCUSSIONS.md](./ANNOUNCING-ON-DISCUSSIONS.md) for the commands and the image handling. -- **X.Y.0:** one new discussion, titled `DocumentDB extension for Visual Studio Code vX.Y Released! `, +Before publishing, always ask the operator: **Is there already a placeholder discussion for this +release? If so, what is its URL?** If a URL was already supplied, confirm that it is the placeholder +to update instead of asking for it again. Wait for the answer; do not create a new discussion unless +the operator confirms there is no placeholder. Reuse a confirmed placeholder by updating its title +and body. + +- **X.Y.0:** one discussion (reuse the placeholder if present), titled `DocumentDB extension for Visual Studio Code vX.Y Released! `, with the release notes as the body. Point `releaseNotesUrl` in `package.json` at it and pin it. -- **X.Y.Z (patch):** first create a new discussion titled `Patch Release vX.Y.Z 📎` whose body is the +- **X.Y.Z (patch):** first create or update the dedicated discussion titled `Patch Release vX.Y.Z 📎` whose body is the `## Patch Release vX.Y.Z` section; then post the same text as a comment on the X.Y.0 announcement. + A patch placeholder is for the dedicated patch discussion, not the parent X.Y.0 announcement. Find that announcement by title (`vX.Y Released`) and content, not through `releaseNotesUrl`: a patch can target an older version. If the lookup is not a single clear match, ask the operator. Keep this order: it puts the X.Y.0 announcement first and the patch post second in the @@ -163,4 +170,5 @@ Before completing: - [ ] `docs/index.md` Release Notes section updated with link to new version - [ ] Screenshot question was answered - [ ] Every requested screenshot is framed with [documentation-screenshots](../documentation-screenshots/SKILL.md), saved under `docs/release-notes/images/` and referenced -- [ ] Announcement posted per [ANNOUNCING-ON-DISCUSSIONS.md](./ANNOUNCING-ON-DISCUSSIONS.md) (for a patch: new `Patch Release vX.Y.Z 📎` discussion first, then the same text as a comment on the X.Y.0 announcement) +- [ ] Placeholder question answered (or supplied URL confirmed), and any confirmed placeholder reused +- [ ] Announcement posted per [ANNOUNCING-ON-DISCUSSIONS.md](./ANNOUNCING-ON-DISCUSSIONS.md) (for a patch: create or update the dedicated `Patch Release vX.Y.Z 📎` discussion first, then post the same text as a comment on the X.Y.0 announcement) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2eb6df1e5..38d0efdea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -413,8 +413,10 @@ Based on the `docs/release-notes/X.Y.md` file, announce the release in the **Ann An agent can do this for you with the `writing-release-notes` skill. The full commands, including how to handle images, are in [ANNOUNCING-ON-DISCUSSIONS.md](.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md). -- **Minor or major release (`X.Y.0`):** create one new discussion titled `DocumentDB extension for Visual Studio Code vX.Y Released! ` with the release notes as the body. Copy its URL into the `releaseNotesUrl` field in `package.json` so users see the announcement from inside the extension, then pin it in place of the previous announcement. -- **Patch release (`X.Y.Z`):** first create a new discussion titled `Patch Release vX.Y.Z 📎` whose body is the `## Patch Release vX.Y.Z` section of the release notes. Then post the same text as a comment on the `X.Y.0` announcement of the version being patched. Find that announcement by its title (`vX.Y Released`) and check its content; do not assume it is the one `releaseNotesUrl` points to, because a patch can target an older version. Keep this order: Announcements are listed by most recent activity, so the comment brings the `X.Y.0` announcement back to the top with the patch post right below it. Leave `releaseNotesUrl` unchanged. +Before publishing, the agent must ask whether a placeholder discussion already exists and collect its URL, or confirm a URL already supplied. Wait for the answer and update the confirmed placeholder's title and body. Create a new discussion only when the operator confirms there is no placeholder. + +- **Minor or major release (`X.Y.0`):** create or update one discussion titled `DocumentDB extension for Visual Studio Code vX.Y Released! ` with the release notes as the body. Copy its URL into the `releaseNotesUrl` field in `package.json` so users see the announcement from inside the extension, then pin it in place of the previous announcement. +- **Patch release (`X.Y.Z`):** first create or update the dedicated discussion titled `Patch Release vX.Y.Z 📎` whose body is the `## Patch Release vX.Y.Z` section of the release notes. A patch placeholder is for this dedicated discussion, not the parent announcement. Then post the same text as a comment on the `X.Y.0` announcement of the version being patched. Find that announcement by its title (`vX.Y Released`) and check its content; do not assume it is the one `releaseNotesUrl` points to, because a patch can target an older version. Keep this order: Announcements are listed by most recent activity, so the comment brings the `X.Y.0` announcement back to the top with the patch post right below it. Leave `releaseNotesUrl` unchanged. ### 7.6 Commit the version bump