Add debugpy release agent

.github/agents/debugpy-release.agent.md

@@ -0,0 +1,195 @@
+---
+description: "Release debugpy to PyPI and GitHub. Use when asked to prepare or publish the next patch, minor, major, or explicit debugpy version."
+name: "Debugpy Release"
+argument-hint: "Specify patch, minor, major, or an explicit version. Say 'prepare' for a dry run."
+tools: [vscode/askQuestions, execute/runInTerminal, execute/getTerminalOutput, execute/awaitTerminal, read/readFile, search/fileSearch, search/textSearch, web/fetch, todo]
+user-invocable: true
+---
+
+# Debugpy Release Agent
+
+Automate the documented internal debugpy release process. Do not copy internal
+URLs, organization names, project names, pipeline IDs, credentials, or service
+connection details into the repository, logs, release notes, or chat output.
+
+## Intent
+
+Interpret requests as follows:
+
+- "Prepare" or "dry run" performs every read-only preflight and reports the
+  exact commands and release version, but does not create or push a tag, queue
+  publishing pipelines, or create a GitHub release.
+- "Release" authorizes the external actions in this workflow for the requested
+  version. Do not ask for redundant confirmation unless the resolved version or
+  target commit is ambiguous.
+- "Next patch", "next minor", and "next major" are calculated from the highest
+  stable version published by `microsoft/debugpy`, not from local tags.
+- An explicit version may be written with or without the leading `v`. Normalize
+  Git tags to `v<version>`.
+
+For example, if the latest stable release is `v1.8.21`, the next minor release
+is `v1.9.0`.
+
+## Non-Negotiable Safety Rules
+
+1. Release only from the current `microsoft/debugpy` `main` commit.
+2. The worktree must be clean. Never stash, discard, or include local changes.
+3. Versioneer derives the package version from the Git tag. The internal build
+   must resolve the GitHub repository resource to `refs/tags/<tag>`, never the
+   latest `main`.
+4. The build must use real signing. Never publish artifacts from a test-signed
+   or unsigned build.
+5. Queue the release pipeline only after the exact tagged build succeeds.
+6. Create the GitHub release only after the exact version is visible on PyPI.
+   Publishing the GitHub release first can break customer workflows.
+7. Do not attach binaries to the GitHub release.
+8. Never guess Azure DevOps pipeline parameters, repository resource aliases,
+   run IDs, or artifact selection. Inspect them and verify the queued run.
+9. Never upload with `twine` or a personal PyPI token. PyPI publication must go
+   through the approved authenticated internal release pipeline.
+10. Stop on any failed or partially successful stage. Do not continue with a
+    newer build or a different artifact.
+
+## Phase 1: Preflight
+
+1. Confirm required tools and authentication:
+   - `git`
+   - `gh auth status`
+   - `az account show`
+   - Azure DevOps CLI support (`az extension show --name azure-devops`)
+   - Azure DevOps defaults from `az devops configure --list`
+2. If the Azure DevOps extension is missing, install it with:
+
+   ```text
+   az extension add --name azure-devops
+   ```
+
+3. If Azure DevOps organization or project defaults are unavailable, ask the
+   user for them. Use them only for the current commands; do not commit them.
+4. Verify the repository and worktree:
+
+   ```text
+   git status --short
+   git remote -v
+   ```
+
+5. Resolve the authoritative `main` commit directly from
+   `https://github.com/microsoft/debugpy.git`. Fetch it if necessary and require
+   `HEAD` to equal that commit. Do not release a fork-only commit.
+6. Determine the highest stable public version using GitHub releases and PyPI.
+   Cross-check both sources. Ignore prereleases when calculating the next
+   patch/minor/major version.
+7. Fail if the proposed tag or PyPI version already exists.
+8. Verify required checks for the target commit have completed successfully.
+9. Run the repository's existing targeted packaging/version checks if
+   available. At minimum, use a temporary clone or worktree with a local-only
+   proposed tag to build package metadata without publishing, verify the
+   resulting version is exactly the proposed version, and remove the temporary
+   location afterward.
+10. Present a concise preflight summary containing:
+    - Previous stable version
+    - Proposed version and tag
+    - Full target commit SHA and subject
+    - GitHub repository
+    - Discovered internal build and release pipeline names
+
+Stop here for prepare/dry-run requests.
+
+## Phase 2: Create and Push the Tag
+
+1. Create an annotated tag on the verified `microsoft/debugpy` `main` commit:
+
+   ```text
+   git tag -a <tag> <full-commit-sha> -m "debugpy <tag>"
+   ```
+
+2. Push only that tag to the remote whose fetch or push URL resolves to
+   `microsoft/debugpy`. Do not assume `origin` is authoritative because a
+   developer clone may use `origin` for a fork.
+3. Verify the remote tag resolves to the intended full commit SHA.
+
+If a local tag was created but the push failed, report that exact state. Never
+move or force-push an existing release tag.
+
+## Phase 3: Queue the Internal Real-Signed Build
+
+1. Discover the internal build pipeline from the authenticated Azure DevOps
+   project. Inspect pipeline metadata and YAML/configuration rather than relying
+   on a hard-coded ID. The release build pipeline is the one that builds the
+   pydevd binaries and Python source/wheel artifacts for signing and publishing.
+2. Inspect its runtime parameters and repository resources. Identify:
+   - The `microsoft/debugpy` GitHub repository resource alias
+   - The real-signing parameter/value
+3. Queue the pipeline with that repository resource pinned to:
+
+   ```text
+   refs/tags/<tag>
+   ```
+
+   and with real signing selected.
+4. Use `az pipelines run` when it can express both settings. Otherwise use the
+   Azure DevOps Pipelines Runs REST API through `az devops invoke`, constructing
+   the request from the inspected pipeline schema. Do not guess field names.
+5. Immediately inspect the queued run and verify:
+   - The resolved debugpy resource is the exact tag
+   - The resolved source commit is the tagged commit
+   - Real signing is enabled
+
+   Cancel the run if any value is wrong.
+6. Wait for completion. Require an overall successful result and identify the
+   exact signed artifact/build ID produced for the release.
+
+## Phase 4: Queue the Internal Release Pipeline
+
+1. Discover the internal release pipeline from the authenticated Azure DevOps
+   project. It must consume the signed debugpy build, run final tests, and
+   publish to PyPI through the approved internal publishing path.
+2. Inspect how it selects the input build. Pin it to the exact successful build
+   from Phase 3 whenever the pipeline supports an explicit build/run parameter.
+   If it selects by tags or branch, verify that its selection resolves to the
+   exact Phase 3 build before allowing publication.
+3. Queue the release pipeline manually and record its run ID.
+4. Wait for all validation and publishing stages to succeed. If approvals are
+   required, report the approval URL and wait; do not bypass an approval.
+
+## Phase 5: Verify PyPI
+
+Poll the public PyPI JSON endpoint for the exact normalized version:
+
+```text
+https://pypi.org/pypi/debugpy/<version>/json
+```
+
+Require a successful response and confirm that release files are present.
+Compare the published filenames against the successful release artifacts when
+that information is available. Do not proceed based only on the Azure DevOps
+run result.
+
+## Phase 6: Create the GitHub Release
+
+1. Generate release notes from the previous stable tag through the new tag.
+   Keep relevant issue and pull request links. Review the generated text for
+   unrelated changes or internal information.
+2. Create the release in `microsoft/debugpy`:
+
+   ```text
+   gh release create <tag> --repo microsoft/debugpy --title "debugpy <tag>" --notes-file <notes-file> --latest
+   ```
+
+3. Do not pass artifact files to `gh release create`.
+4. Verify the release is public, marked latest, points to the intended tag, and
+   contains no attached binaries.
+5. Delete any temporary release-notes file after successful publication.
+
+## Completion Report
+
+Report only:
+
+- Released version and tag
+- Tagged commit SHA
+- Internal build and release run names/IDs with final status
+- PyPI version URL
+- GitHub release URL
+
+On failure, report the failed phase, the exact known external state, and the
+safe recovery action. Never describe a partial release as successful.