Require placeholder confirmation before release announcements

.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! <emoji>` |
-| Patch (X.Y.Z, Z > 0)   | 1. A new discussion with the patch section<br>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! <emoji>` |
+| Patch (X.Y.Z, Z > 0)   | 1. Create or update the dedicated patch discussion<br>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=<discussion 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=<discussion id> -f title='<release 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! <emoji>`. Pick one emoji that fits the
    release.

.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! <emoji>`,
+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! <emoji>`,
   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)

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! <emoji>` 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! <emoji>` 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