From 4728fd02bddac55cbcdd3d7b9e1f6594f2b5a276 Mon Sep 17 00:00:00 2001 From: Tomasz Naumowicz Date: Tue, 20 Oct 2026 10:39:38 +0000 Subject: [PATCH 1/2] docs: require placeholder confirmation before release announcements Ask whether a release discussion placeholder exists before publishing, and reuse a confirmed placeholder instead of creating a duplicate. Preserve version-based parent lookup and publish-before-comment ordering for patch announcements. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../ANNOUNCING-ON-DISCUSSIONS.md | 46 +++++++++++++++++-- .github/skills/writing-release-notes/SKILL.md | 14 ++++-- CONTRIBUTING.md | 6 ++- 3 files changed, 56 insertions(+), 10 deletions(-) diff --git a/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md b/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md index ff838bf31..4fcd1be1d 100644 --- a/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md +++ b/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md @@ -6,13 +6,46 @@ 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) | +| 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 e8f9bec79..a1a44fcf1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -403,8 +403,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 From fea4d12e437a73d5b79f30037dbeb4a2ca1fdf35 Mon Sep 17 00:00:00 2001 From: Tomasz Naumowicz Date: Tue, 20 Oct 2026 10:53:12 +0000 Subject: [PATCH 2/2] style: format release announcement placeholder guidance Apply the repository formatter to the placeholder-reuse documentation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md b/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md index 4fcd1be1d..0862d2fd0 100644 --- a/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md +++ b/.github/skills/writing-release-notes/ANNOUNCING-ON-DISCUSSIONS.md @@ -4,10 +4,10 @@ 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 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) | +| 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