release-note-writer

by microsoft

Guidelines for writing and reviewing Insiders and Stable release notes for Visual Studio Code.

npx skills add https://github.com/microsoft/vscode-docs --skill release-note-writer
Download ZIPGitHub
6.6k

Visual Studio Code Release Note Writer Guidelines

This skill is designed to help you write release notes for Visual Studio Code Insiders and Stable releases. It provides structured guidelines and examples to ensure consistency and clarity in the release notes.

There are two main types of release notes you can generate using this skill:

  1. Insiders Release Notes: These notes cover the latest features and updates in the Insiders build of VS Code. They are updated frequently as new features are added. Their format includes sections grouped by the date of the updates. The content is generated based on closed GitHub issues and PRs for a specific milestone.

  2. Stable Release Notes: These notes summarize the key features and improvements in a stable release of VS Code. They follow a more structured format with predefined sections for different feature areas. The release is initially created using a template and then updated by the engineering team.

Your task is help generate these release notes based on the provided guidelines, examples, and templates.

General writing guidelines for release notes

Follow the guidelines in this order of priority:

  1. Release notes writing instructions
  2. Visual Studio Code documentation writing guidelines

Insiders Release Notes

Insiders release notes cover the latest features and updates in the Insiders build of VS Code. They are updated frequently as new features are added. Their format includes sections grouped by the date of the updates. The content is generated based on closed GitHub issues and PRs for a specific milestone.

Your task is to generate release notes for the specified VS Code Insiders release version based on GitHub issues and PRs.

Input parameters

If no release version is specified, ask the user for the release version. If no milestone name is specified, check if the milestone name is in the frontmatter, otherwise ask the user for the milestone name. If no label is specified, use the "feature-request" label by default.

DO NOT continue until you have the release version and milestone name!!

File format

Issues are grouped in H2 sections by their closed date. The TOC must be updated to reflect the new sections and issues added.

Use this template for the Insiders release notes.

The 1.109 release notes are a concrete example of an Insiders release note.

Generation steps

  1. If there is not an existing Insiders release note for the specified version, create a new release note file using the Insiders release note template and replace the placeholders.

    Release notes are stored in the /release-notes folder with the filename format v<version>.md, e.g., v1_109.md.

  2. Make sure to copy the following images to the appropriate images folder (/release-notes/images/<version with underscores>, e.g. 1_110) for the release version:

    • vscode-insiders-header.webp
    • vscode-insiders-banner-medium.png

  3. Get last update date from existing release notes for the specified release version. If no existing release notes, disregard last update date.

  4. Run a subagent to fetch all closed GitHub issues in the microsoft/vscode repo for the milestone that have the specified label and closed date as of the latest update date by using the github CLI. Save the JSON in the release note document.

    Use this CLI command: gh search issues --repo microsoft/vscode --label <label name> --milestone <milestone name> --state closed "closed:>=<latest update date>" -L 100

  5. Ignore issues that are marked as duplicate or not planned.

  6. For each issue in the JSON result, run a subagent to update the release notes and TOC with a concise technically accurate summary of the issue. Get more details from the associated PRs if needed. At the end of the summary, include a link to the GH issue which include the issue number and title (format: #12345: Issue title). Group issues under an H2 section that represents the closed date.

Phrasing guidelines for Insiders entries

  • When describing new capabilities, prefer the format "Add support for ..." over "... now supports ...". For example, write "Add support for sorting sessions by date" rather than "The sessions view now supports sorting by date".
  • Avoid using the word "now" in entries. State what changed directly instead. For example, write "Branch names are generated based on the user's prompt" rather than "Branch names are now generated based on the user's prompt".

Stable Release Notes

Stable release notes summarize the key features and improvements in a stable release of VS Code. They follow a more structured format with predefined sections for different feature areas. The release is initially created using a template and then updated by the engineering team.

Input parameters

If no release version is specified, ask the user for the release version. If no release month and year are specified, ask the user for the release month and year. DO NOT continue until you have the release version and release month and year!!

File format

Use this template for generating the initial Stable release notes.

Generation steps

  1. If there is not an existing release note for the specified version, create a new release note file using the Stable release note template.

    Release notes are stored in the /release-notes folder with the filename format v<version>.md, e.g., v1_109.md.

  2. If there is an existing release note for the specified version, and it's an Insiders release note, replace the content with the Stable release note template content.

  3. If there is an existing Stable release note for the specified version, perform a code review of the existing release note to ensure it adheres to the writing guidelines. Suggest improvements as needed.

Value proposition and feature framing

The writing instructions define the value-proposition and feature-continuity rules. When writing Stable entries, keep these essentials top of mind:

  • Open each entry with the user benefit or the problem being solved, then explain mechanics.
  • For multi-release features, re-establish context in 1-2 sentences so the entry stands on its own.
  • For admin/policy features, cover both the admin use case and the developer-facing impact.
  • Prefer concrete examples and before/after comparisons over vague claims.

Verify context gaps with the user

After a first pass of all feature sections, review the draft for gaps you cannot resolve from the issue, PR, or existing docs. Batch all gaps into a single ask-questions prompt rather than interrupting per section. Ask when:

  • Value prop unclear: You cannot confidently write a benefit-first opening from the source material.
  • Multi-release context missing: A feature builds on prior work but you cannot find earlier entries to reference.
  • Audience ambiguous: Framing differs depending on whether the audience is developers, admins, or extension authors.
  • Docs coverage thin: A feature references a concept that is undocumented or only mentioned as a sidenote, and you need guidance on how much to explain inline.

For each gap, include your best-guess draft so the user can confirm or correct rather than write from scratch.

Before asking, search the docs/ folder for any referenced concepts. If docs coverage is thorough, link to the page and skip the question. Only flag concepts where coverage is thin or absent.

Recovery release notes

When a recovery release is needed, a note is added to the top of the release notes that links to the issues resolved in the recovery release. In addition, the download version is updated to the recovery release version. The rest of the release notes remain unchanged.

Perform these steps to update the release notes for a recovery release:

  1. Update the DownloadVersion in the frontmatter to the recovery release version.

  2. Add a note at the top of the release notes, right after the release date, that links to the issues resolved in the recovery release:

    **Update <recovery version>**: The update addresses these [issues](https://github.com/microsoft/vscode/issues?q=is%3Aissue+is%3Aclosed+milestone%3A<recovery version>).

    When multiple recovery releases are needed, add the note for each recovery release in chronological order.

Review Procedure

To review release notes, follow the full review procedure. This covers both standalone review and post-write validation, with checklists for Insiders and Stable release notes.

More skills from microsoft

oss-growth
microsoft
OSS growth hacker persona
official
microsoft-foundry
microsoft
Deploy, evaluate, and manage Foundry agents end-to-end: Docker build, ACR push, hosted/prompt agent create, container start, batch eval, continuous eval, prompt optimizer workflows, agent.yaml, dataset curation from traces. USE FOR: deploy agent to Foundry, hosted agent, create agent, invoke agent, evaluate agent, run batch eval, continuous eval, continuous monitoring, continuous eval status, optimize prompt, improve prompt, prompt optimizer, optimize agent instructions, improve agent...
officialdevelopmentdevops
azure-ai
microsoft
Use for Azure AI: Search, Speech, OpenAI, Document Intelligence. Helps with search, vector/hybrid search, speech-to-text, text-to-speech, transcription, OCR. WHEN: AI Search, query search, vector search, hybrid search, semantic search, speech-to-text, text-to-speech, transcribe, OCR, convert text to speech.
officialdevelopmentapi
azure-deploy
microsoft
Execute Azure deployments for ALREADY-PREPARED applications that have existing .azure/deployment-plan.md and infrastructure files. DO NOT use this skill when the user asks to CREATE a new application — use azure-prepare instead. This skill runs azd up, azd deploy, terraform apply, and az deployment commands with built-in error recovery. Requires .azure/deployment-plan.md from azure-prepare and validated status from azure-validate. WHEN: "run azd up", "run azd deploy", "execute deployment",...
officialdevopsaws
azure-storage
microsoft
Azure Storage Services including Blob Storage, File Shares, Queue Storage, Table Storage, and Data Lake. Answers questions about storage access tiers (hot, cool, cold, archive), when to use each tier, and tier comparison. Provides object storage, SMB file shares, async messaging, NoSQL key-value, and big data analytics. Includes lifecycle management. USE FOR: blob storage, file shares, queue storage, table storage, data lake, upload files, download blobs, storage accounts, access tiers,...
officialdevelopmentdatabase
azure-diagnostics
microsoft
Debug Azure production issues on Azure using AppLens, Azure Monitor, resource health, and safe triage. WHEN: debug production issues, troubleshoot app service, app service high CPU, app service deployment failure, troubleshoot container apps, troubleshoot functions, troubleshoot AKS, kubectl cannot connect, kube-system/CoreDNS failures, pod pending, crashloop, node not ready, upgrade failures, analyze logs, KQL, insights, image pull failures, cold start issues, health probe failures,...
officialdevopsdevelopment
azure-prepare
microsoft
Prepare Azure apps for deployment (infra Bicep/Terraform, azure.yaml, Dockerfiles). Use for create/modernize or create+deploy; not cross-cloud migration (use azure-cloud-migrate). DO NOT USE FOR: copilot-sdk apps (use azure-hosted-copilot-sdk). WHEN: "create app", "build web app", "create API", "create serverless HTTP API", "create frontend", "create back end", "build a service", "modernize application", "update application", "add authentication", "add caching", "host on Azure", "create and...
officialdevelopmentdevops
azure-validate
microsoft
Pre-deployment validation for Azure readiness. Run deep checks on configuration, infrastructure (Bicep or Terraform), RBAC role assignments, managed identity permissions, and prerequisites before deploying. WHEN: validate my app, check deployment readiness, run preflight checks, verify configuration, check if ready to deploy, validate azure.yaml, validate Bicep, test before deploying, troubleshoot deployment errors, validate Azure Functions, validate function app, validate serverless...
officialdevopstesting