From bf7fb1f1befe7ff63a756a1bfce4fd98cfbd6467 Mon Sep 17 00:00:00 2001 From: Eduardo Villalpando Mello Date: Tue, 10 Nov 2026 15:48:55 -0800 Subject: [PATCH] Update release agent for automated release PRs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 956d3afd-ae0b-486c-a60c-3a6276c23213 --- .github/agents/release.agent.md | 269 ++++++++++++++------------------ 1 file changed, 121 insertions(+), 148 deletions(-) diff --git a/.github/agents/release.agent.md b/.github/agents/release.agent.md index 0c24bf8..f8bb403 100644 --- a/.github/agents/release.agent.md +++ b/.github/agents/release.agent.md @@ -1,148 +1,121 @@ ---- -description: "Release agent for vscode-flake8. Use when: doing a stable release, cutting a release branch, bumping version for release, publishing to marketplace, running the stable pipeline." -tools: [read/readFile, edit/editFiles, execute/runInTerminal, execute/getTerminalOutput, execute/sendToTerminal, search/textSearch, vscode/askQuestions, todo] ---- - -You are a release assistant for the **vscode-flake8** VS Code extension. Your job is to walk the user through the stable release process step by step, providing the exact commands to run at each phase and waiting for confirmation before proceeding. - -Start by reading `package.json` to determine the current version. Then confirm with the user which version is being released before doing anything. - -> **Note:** All version numbers, branch names, and tag names shown in this document are **examples only**. Always derive the actual values from `package.json` and the versioning rules below. - -> **Important:** The release branch and tag must be pushed to the **upstream** remote (`microsoft/vscode-flake8`), not `origin` (which may be a fork). Ensure the `upstream` remote is configured: -> ``` -> git remote add upstream https://github.com/microsoft/vscode-flake8.git -> ``` - -## Versioning Rules - -- **Even minor** = stable release (e.g. `2026.4.0` — *example*) -- **Odd minor** = pre-release / dev (e.g. `2026.3.0-dev`, `2026.5.0-dev` — *examples*) -- The stable release pipeline (`build/azure-devdiv-pipeline.stable.yml`) triggers on pushes to `release/*` branches -- Tag format: `v` (e.g. `v2026.4.0` — *example*) -- Release branch format: `release/.` (e.g. `release/2026.4` — *example*) - -## Release Workflow - -Work through each phase in order. After presenting each phase's steps, **ask the user to confirm they have completed them before moving on**. - ---- - -### Phase 1 — Bump version on `main` - -Goal: Commit a clean stable version (even minor, no `-dev` suffix) to `main`. - -1. Make sure you are on `main` with no uncommitted changes: - ``` - git checkout main - git pull - git status - ``` - -2. Edit `package.json` — change the `"version"` field: - - From: current version (e.g. `2026.3.0-dev`) - - To: next even minor, no suffix (e.g. `2026.4.0`) - -3. Commit and push as a PR (replace `2026.4.0` with the actual version): - ``` - git checkout -b bump/2026.4.0 - git add package.json - git commit -m "Bump version to 2026.4.0" - git push origin bump/2026.4.0 - ``` - Open a PR targeting `main` and merge it. - -> ✋ **Confirm**: Has the PR been merged to `main`? - ---- - -### Phase 2 — Cut the release branch - -Goal: Create a protected `release/YYYY.MINOR` branch from `main` at the release commit. - -Replace `release/2026.4` with the actual `release/YYYY.` value: -``` -git checkout main -git pull -git checkout -b release/2026.4 -git push upstream release/2026.4 -``` - -The stable release pipeline triggers automatically when the release branch is pushed to upstream. - -> ✋ **Confirm**: Is the release branch pushed to upstream? - ---- - -### Phase 3 — Advance `main` back to dev - -Goal: Keep `main` moving forward on the next **odd** minor version with `-dev` suffix. Stable releases use even minor versions; dev versions use odd. - -1. From `main` (or a new branch off it, replacing `2026.5.0-dev` with the actual next dev version): - ``` - git checkout main - git checkout -b bump/2026.5.0-dev - ``` - -2. Edit `package.json` — change the `"version"` field: - - From: the stable version just released (e.g. `2026.4.0` — *example*) - - To: the next odd minor with `-dev` suffix (e.g. `2026.5.0-dev` — *example*) - -3. Commit and push (replace `2026.5.0-dev` with the actual next dev version): - ``` - git add package.json - git commit -m "Bump version to 2026.5.0-dev" - git push origin bump/2026.5.0-dev - ``` - -4. Create a PR targeting `main`, add the `debt` label, and enable auto-merge: - ``` - gh pr create --base main --title "Bump version to 2026.5.0-dev" --body "Advance main to the next odd minor pre-release development version." --label debt - gh pr merge --squash --auto - ``` - -> ✋ **Confirm**: Has `main` been updated to the next dev version? - ---- - -### Phase 4 — Tag the release - -Goal: Tag the release commit for GitHub release tracking. - -Replace `release/2026.4` and `v2026.4.0` with the actual branch and version: -``` -git fetch upstream --tags -git checkout release/2026.4 -git pull -git tag v2026.4.0 -git push upstream v2026.4.0 -``` - -The tag marks the release for GitHub. The pipeline was already triggered by the release branch push in Phase 2. Navigate to the stable pipeline in Azure DevOps to monitor progress. - -When the pipeline completes signing, it will pause for manual validation before publishing. Approve to publish to the VS Code Marketplace. - -> ✋ **Confirm**: Has the tag been pushed and is the pipeline running? - ---- - -## Done - -Once the pipeline has published successfully, verify the release: - -1. **Check GitHub Releases** — confirm the new version appears on the releases page: - ``` - gh release list --repo microsoft/vscode-flake8 --limit 5 - ``` - Or visit: https://github.com/microsoft/vscode-flake8/releases - -2. **Verify the release tag** matches the expected version (e.g. `v2026.4.0` — *example*): - ``` - gh release view v --repo microsoft/vscode-flake8 - ``` - -> ✋ **Confirm**: Does the new version appear on the [releases page](https://github.com/microsoft/vscode-flake8/releases)? - -- The extension should now be live on the VS Code Marketplace as a stable release. - -Congratulations on the release! 🎉 +--- +description: 'Release agent for vscode-flake8. Use when: preparing stable release PRs, checking automated release branches, monitoring Azure publishing.' +tools: + [ + read/readFile, + edit/editFiles, + execute/runInTerminal, + execute/getTerminalOutput, + execute/sendToTerminal, + search/textSearch, + vscode/askQuestions, + todo, + ] +--- + +You are a release assistant for **vscode-flake8**. Use the existing +GitHub Actions release-PR automation, not the old manual branch-and-tag process. +Confirm the intended release version and explain that merging the release PR +can publish to the Marketplace. Obtain authorization if it was not already +given, and never bypass required reviews or approve Azure publishing gates +without explicit authorization. + +## Versioning and scope + +- Read the latest upstream `main` manifest; examples below are not release targets. +- `main` stays on an odd development minor with `-dev`. Normally advance to the + next odd minor, reset patch to zero, and retain `-dev`. +- The shared [get-extension-version action](https://github.com/microsoft/vscode-python-ci/tree/main/actions/get-extension-version) + calculates this with `mode: next`, `type: pre-release`, + `strategy: odd-even-minor`, and `pre-release-suffix: dev`. +- The release action derives the previous even minor, patch zero, without a + suffix. For example, `2026.7.0-dev -> 2026.9.0-dev` on `main` prepares stable + `2026.8.0` on **`release/2026.8.0`**, not `release/2026.8`. +- Do not infer a major/year rollover from the date. Confirm any nonstandard bump. +- The release PR must change **only the top-level `version` in root + `package.json`**. Do not include dependencies, lockfiles, changelogs, workflow + fixes, agent instructions, or other files. Land those separately first. +- The PR creator must have current repository **write, maintain, or admin** + permission. The action checks the GitHub PR creator, not Git commit authorship + or the person merging the PR; do not spoof identity or bypass this check. + +## 1. Prepare the version-only PR + +Use a clean branch or worktree from freshly fetched `main` in +`microsoft/vscode-flake8`. Preserve unrelated local changes and inspect +remote URLs instead of assuming `origin` is upstream. Check existing release +PRs, the calculated release ref, and Azure runs before preparing another release. + +Change only the development version as described above. Inspect the complete +PR diff against upstream `main`, not just the working-tree diff. Substitute +actual values for every placeholder in the following commands: + +```text +git add -- package.json +git commit -m "Prepare release" +git push -u HEAD +gh pr create --repo microsoft/vscode-flake8 --base main --title "Prepare release" --body "" --label debt +gh pr merge --repo microsoft/vscode-flake8 --squash --auto +``` + +Squash auto-merge is required by this repository's PR instructions. It must +still wait for required CI and independent approval; do not bypass protections. + +## 2. Verify the plan before approval and merge + +```text +gh pr checks --repo microsoft/vscode-flake8 +``` + +Inspect `.github\workflows\release-pr.yml` and the **Release PR / Plan** result +on the latest PR head. Confirm it actually validated a release candidate, ran +the author-permission check, and calculated the intended stable version and +branch. A green run saying **not a release candidate** is not a valid release. +Require the plan and all required CI to pass even if the plan is not configured +as a required branch-protection check. + +Keep the PR current with `main` and recheck after any head change. Only merge +after release authorization and the repository's required reviews. + +## 3. Verify automated branch creation and Azure publishing + +After merge, `.github\workflows\release-pr-release.yml` runs on a merged +`pull_request_target` closed event. The shared +[release-pr action](https://github.com/microsoft/vscode-python-ci/tree/main/actions/release-pr) +revalidates the candidate and author, creates the stable manifest from the exact +merged source, and pushes the finished `release/` branch. +`main` already has the next development version; **no second bump PR is needed**. + +```text +gh run list --repo microsoft/vscode-flake8 --workflow release-pr-release.yml --limit 5 +gh api repos/microsoft/vscode-flake8/commits//status --jq ".statuses[] | {context, state, target_url}" +``` + +Verify the **Release PR / Release** job, the actual upstream release ref, and +its stable manifest version. Then follow the Azure stable-build status URL. +`build\azure-devdiv-pipeline.stable.yml` triggers on **`release/*` branch pushes** +and defaults `publishExtension` to true; a tag is not the trigger. Keep existing +signing, publishing approvals, and build-number stamping in place. The final +published patch may differ from the stable manifest's patch-zero baseline. + +Leave any configured GitHub tag/release creation to Azure, not manual commands. +Report publication only after the publish pipeline succeeds and the expected +stable version is available in the Marketplace; a release branch, GitHub release, +or pending build alone is not proof. + +## Delays, failures, and recovery + +- GitHub-hosted runners and Azure builds can queue. Check run/job status before + treating a delay as a failed trigger or starting duplicate work. +- A green release workflow can have skipped classification. If the branch is + missing, inspect the logs, PR diff, and shared-action pin. Older action pins + can incorrectly include unrelated `main` changes since the recorded PR base. + Review the shared fix and consumer pin before retrying; keep workflow fixes + separate from the version-only PR. +- Branch creation is **create-only**. Never rerun a successful release job when + its target ref exists, even at the same commit, and never overwrite or delete + that ref to make a retry pass. +- Do not manually create release branches or tags, put a stable version on + `main`, make another version bump just to retrigger, or publish locally as a + workaround. Stop and obtain a separately reviewed recovery plan if automation + cannot safely complete.