vscode-aks-tools-release-pr

name	vscode-aks-tools-release-pr
description	Prepare a release PR for the Azure/vscode-aks-tools VS Code extension. Bumps version in package.json and package-lock.json, creates a new What's New doc, updates SUMMARY.md / release.md / README.md / releasing.md, and removes stale prior-release files. WHEN: 'make a release PR', 'release vscode-aks-tools', 'bump extension version', 'create publish-x.y.z branch', 'prepare release notes for aks tools', 'what's new file for next release'. DO NOT USE FOR: actually publishing to the marketplace (that runs via the internal 1ES pipeline), changelog backfill (CHANGELOG.md is deprecated since 1.6.14), or unrelated repos.
argument-hint	Target version (e.g., 2.1.0). Optionally describe release highlights.

vscode-aks-tools Release PR

Prepare a publish-x.y.z release PR for the Azure/vscode-aks-tools VS Code extension.

This skill ONLY prepares the source changes needed for the release PR. The actual marketplace publish is handled by the internal 1ES signed pipeline (.github/workflows/1es-pipeline.yml) — do not attempt to run it.

When to Use

• User asks to cut/prepare/start a new release of the AKS VS Code extension
• User says "bump the version to X.Y.Z" for this repo
• User asks to draft the What's New doc for the next release
• User wants to open a publish-x.y.z PR

When NOT to Use

• Marketplace publishing (handled by internal 1ES pipeline)
• Updating CHANGELOG.md — deprecated since 1.6.14; release notes now live in GitHub Releases + the What's New doc
• Any repo other than Azure/vscode-aks-tools

Inputs

Gather (ask the user if not provided):

1. Target version (semver x.y.z, e.g. 2.1.0).
2. Release highlights — optional. By default the What's New doc is generated from PRs merged into upstream/main since the previous release tag (see step 6). The user may override or augment that list.
3. Whether to remove the previous What's New file — default YES (only the current release's file is kept).

Procedure

1. Verify Repo and Working State

git rev-parse --show-toplevel    # must end in /vscode-aks-tools (or a worktree of it)
git remote -v                    # confirm `upstream` points to Azure/vscode-aks-tools
git status --short               # must be clean

If not clean, stop and ask the user.

2. Establish the Release Branch

Per docs/book/src/release/releasing.md, the convention is publish-x.y.z.

git fetch upstream main
git checkout -b publish-<x.y.z> upstream/main

If the user already created a branch and is on it, skip this step.

3. Identify Current and Previous Versions

• Current version: read "version" from root package.json.
• Previous What's New file: ls docs/book/src/release/whats-new-*.md. There should normally be exactly one.

4. Bump Version in package.json and package-lock.json

Use npm version to update both files atomically (no git tag, no commit):

npm version <x.y.z> --no-git-tag-version --allow-same-version

This updates:

• root package.json → "version"
• root package-lock.json → top-level "version" AND packages."".version

Do NOT run npm install (we are not changing dependencies and do not want lockfile churn). If npm version is unavailable, edit the three fields manually.

webview-ui/package.json is marked "private": true with version "0.0.0" — do NOT bump it.

5. Audit Other Version References

Run this audit and report findings to the user before changing anything beyond the files in step 4:

# Search for the OLD version as a project version (not a dependency range)
grep -rn --include='*.json' --include='*.ts' --include='*.md' --include='*.yml' --include='*.yaml' \
  -e "\"version\": \"<old-version>\"" \
  -e "vscode-aks-tools.*<old-version>" \
  .

Expected hits (must update):

• package.json (line ~5)
• package-lock.json (root + packages."")

Known false positives (do NOT touch):

• .vscode/tasks.json — "version": "2.0.0" is the tasks file schema version
• Any "@azure/*" dependency versions
• Any node / engines fields

If any hit doesn't fit the above, surface it to the user before editing.

6. Create the New What's New Doc

Path: docs/book/src/release/whats-new-<x.y.z>.md

Source the content from merged PRs since the last release. Do not invent highlights.

6a. Collect merged PRs since the previous release

Find the previous release tag, then list every PR merged into main since that tag was cut:

# Previous release tag — Azure/vscode-aks-tools tags releases as `x.y.z` (no `v` prefix; verify with `git tag --sort=-v:refname | head -5`)
PREV=$(git tag --sort=-v:refname | head -1)

# Cutoff date = commit date of the previous release tag (ISO 8601)
SINCE=$(git log -1 --format=%cI "$PREV")

# All PRs merged into main since the previous release
gh pr list \
  --repo Azure/vscode-aks-tools \
  --base main \
  --state merged \
  --search "merged:>=$SINCE" \
  --limit 200 \
  --json number,title,author,mergedAt,labels,url \
  > /tmp/release-prs.json

Cross-check with git log --oneline --merges "$PREV"..upstream/main to catch anything gh missed.

6b. Classify and curate

Group the PRs into:

• Headline features — new user-visible commands, panels, integrations, feature flags
• Improvements / fixes — bug fixes, UX polish, perf, telemetry
• Dependencies & infra — dependabot, build, CI, docs-only changes

Drop the dependency/infra bucket from the body unless the user wants it called out. Bot-authored PRs (e.g., dependabot[bot]) should be summarised in one line, not listed individually.

For each headline item, capture: PR number, one-sentence summary in user terms (not commit-message voice), and link target — prefer the corresponding feature doc under docs/book/src/features/ over the PR URL.

Ask the user to confirm the curated list before drafting the doc.

6c. Collect contributor acknowledgements

This repo's CHANGELOG.md history ends every release with a thank-you line. Mirror that in the What's New doc:

jq -r '.[].author.login' /tmp/release-prs.json | sort -u

Exclude bots (*[bot]). Render as: Thanks to @user1, @user2, ... for contributions, testing, and reviews.

6d. Draft the doc

Use the existing latest file as the template (same headings, same screenshot conventions). Mandatory sections:

# What's New in <x.y.z>

<one-paragraph framing — what this release is about, derived from the headline PRs>

## Release focus

<bulleted summary of headline items>

## Feature flags at a glance (omit if none introduced or changed)

## <Numbered feature section per highlight>

Highlights:
- ...

Read full details:
- [Feature doc title](../features/<feature>.md)

## Behavior and compatibility

## Recommended reader path

## Screenshots (only if assets exist under docs/book/src/resources/)

Rules:

• Link to feature docs via relative paths (../features/...).
• Only embed screenshots that actually exist on disk under docs/book/src/resources/. Verify before linking.
• Keep the file readable on mdbook (no HTML-only constructs).

7. Remove the Stale Prior What's New File

git rm docs/book/src/release/whats-new-<prev>.md

The previous What's New is preserved in git history and in the GitHub Release. Only the current release's doc lives in the book.

8. Update Book Navigation and Indexes

These three files all reference the What's New doc and must be updated together:

• docs/book/src/SUMMARY.md — replace the What's New in <prev> line under the - [Release] section.
• docs/book/src/release.md — replace the What's New in <prev> bullet.
• docs/book/src/README.md — replace the What's New in <prev> bullet under ## Development and Release.

Pattern for each: change both the display text (What's New in <prev> → What's New in <new>) and the link target (whats-new-<prev>.md → whats-new-<new>.md).

After edits, run:

grep -rn "whats-new-<prev>" docs/   # must return zero matches
grep -rn "What's New in <prev>" docs/   # must return zero matches

9. Update releasing.md Only If Process Changed

docs/book/src/release/releasing.md documents the release process itself, not a per-release artifact. Do NOT touch it just to bump a version.

Update it only if the user explicitly says the process changed (e.g., new pipeline, new required step, new secret).

docs/maintenance/README.md currently mirrors releasing.md. If you update one, mirror the change to the other and tell the user.

10. CHANGELOG.md — DO NOT UPDATE

Per the deprecation notice at the top of CHANGELOG.md (as of 1.6.14), the changelog is no longer maintained. Release notes live in:

• The new whats-new-<x.y.z>.md doc
• The GitHub Release body (auto-generated by the publish pipeline)

If the user explicitly insists on a CHANGELOG entry, add a ## [x.y.z] section in Keep-a-Changelog format and warn them it's outside current convention.

11. Verify the Build Still Works

npm install --no-audit --no-fund    # only if package-lock looks dirty; usually skip
npm run lint
npm run webpack                     # confirms TS + bundling still succeed

The expensive tests are not required for a version-bump PR; skip them unless the user asks.

12. Commit

Single commit, conventional message:

git add package.json package-lock.json \
        docs/book/src/release/whats-new-<x.y.z>.md \
        docs/book/src/SUMMARY.md \
        docs/book/src/release.md \
        docs/book/src/README.md
# plus `git rm` of the prior whats-new file (already staged by step 7)

git commit -m "chore(release): prepare <x.y.z>"

Never commit without confirming with the user first. (User preference — see /memories/git-worktrees.md.)

13. Push and Open the PR

git push -u origin publish-<x.y.z>
gh pr create \
  --repo Azure/vscode-aks-tools \
  --base main \
  --head <user>:publish-<x.y.z> \
  --title "chore(release): <x.y.z>" \
  --body-file <(cat <<'EOF'
## Release PR for vX.Y.Z

- Bumps `package.json` / `package-lock.json` to `<x.y.z>`
- Adds `docs/book/src/release/whats-new-<x.y.z>.md`
- Removes stale `whats-new-<prev>.md`
- Updates `SUMMARY.md`, `release.md`, `README.md` navigation

After merge, trigger the internal 1ES publish pipeline to push to the marketplace.
EOF
)

Ask the user before pushing. Do not force-push.

Final Checklist

Report this to the user before declaring done:

• package.json version is <x.y.z>
• package-lock.json root + packages."" versions are <x.y.z>
• docs/book/src/release/whats-new-<x.y.z>.md exists and links resolve
• docs/book/src/release/whats-new-<prev>.md deleted
• SUMMARY.md, release.md, README.md reference only <x.y.z>
• No stray references to <prev> in docs/ (grep returns empty)
• CHANGELOG.md untouched (intentional — deprecated)
• Build passes
• Branch is publish-<x.y.z>, off latest upstream/main
• PR opened against Azure/vscode-aks-tools:main

Repo Facts (verified)

• Upstream: https://github.com/Azure/vscode-aks-tools.git
• Default branch: main
• Project version lives in: root package.json + root package-lock.json only
• webview-ui/package.json is private, stays at 0.0.0
• .vscode/tasks.json "version": "2.0.0" is schema, not project version
• Publish workflow: .github/workflows/1es-pipeline.yml (internal signed pipeline)
• CHANGELOG.md deprecated since 1.6.14