Release

Release

Prepare releases safely and reproducibly. Follow .github/copilot-instructions.md and this workflow. This skill is self-contained; do not depend on another skill, agent, or manifest.

Safety boundary

Release preparation and release publication are separate phases.

• Preparation may inspect metadata, create release/X.Y.Z from develop, update VERSION and CHANGELOG.md, run existing validation, push the release branch, and open a pull request targeting main.
• Publication includes creating or pushing a tag, creating or publishing a GitHub Release, publishing a package or container image, or starting any deployment.
• Never perform a publication action without explicit human approval given after presenting the exact version, commit SHA, tag, release title, release notes, artifacts, and publication commands or destinations.
• Approval to prepare a release, merge a pull request, or "continue" is not approval to publish. Ask for publication approval as a distinct final gate.
• Never create, modify, close, merge, or otherwise interfere with an unrelated active release pull request or its workflow runs.
• Never create, modify, or deploy Azure resources as part of release preparation.

1. Establish the authoritative release state

Fetch current remote metadata without changing branches or tags:

git fetch origin develop main --tags --prune
git status --short
git branch --show-current
git log -1 --format=%H origin/develop
git log -1 --format=%H origin/main
git tag --list 'v[0-9]*' --sort=-version:refname
gh release list --limit 100

Read the root VERSION file and the versioned headings in CHANGELOG.md. Determine the latest released version from all authoritative repository surfaces:

1. SemVer tags matching exactly vMAJOR.MINOR.PATCH.
2. Published and draft GitHub Releases whose tag matches that format.
3. The root VERSION value matching exactly MAJOR.MINOR.PATCH.
4. Versioned CHANGELOG.md headings matching ## [vMAJOR.MINOR.PATCH] - YYYY-MM-DD.

Do not infer the latest release from branch names, package metadata, commit messages, pull request titles, or a single surface alone. Ignore prerelease identifiers unless the human explicitly requests a prerelease workflow.

Compare versions using SemVer precedence, not lexical ordering. Record the commit targeted by every relevant tag and release. If tags, releases, VERSION, and changelog disagree, stop normal preparation and enter reconciliation. Never silently select one conflicting value.

2. Select and verify the next version

Use Semantic Versioning:

• PATCH for backward-compatible fixes.
• MINOR for backward-compatible functionality.
• MAJOR for breaking changes.

The requested or proposed version must be strictly greater than the latest released stable version and must not already exist as a tag, GitHub Release, or remote release branch. Present the evidence and proposed increment when the version was not supplied explicitly.

Use these exact forms for release X.Y.Z:

The tag and GitHub Release title must contain no product prefix or suffix.

3. Prepare the release branch

Require a clean worktree. Create the release branch from the fetched origin/develop commit, never from main or a local branch with unpushed changes:

git switch --create release/X.Y.Z origin/develop

On the release branch:

1. Set root VERSION to X.Y.Z without a v prefix.
2. Convert the single top-level ## [Unreleased] section in CHANGELOG.md to ## [vX.Y.Z] - YYYY-MM-DD.
3. Do not leave any [Unreleased] heading on the release branch.
4. Do not add unrelated feature work.
5. Confirm branch name, VERSION, changelog version, release tag, and release title are exactly consistent.

After pushing the release branch, open a pull request from release/X.Y.Z to main. The pull request must explain the release purpose, metadata changes, validation results, and the separate post-merge publication approval gate.

Do not tag a release-branch commit. A release tag may target only the approved commit on main after the release pull request is merged and the merge commit has been verified.

4. Validate the release candidate

Discover and run the repository's existing validation rather than inventing replacement checks. At minimum, run the current unit suite:

pytest -q

Also run any repository-provided Copilot asset validation, lint, build, or release checks that exist at preparation time. Do not add tools merely to make the release pass. Report every command and result. A failure blocks the release; do not publish with a known failing gate unless a human supplies a documented, repository-approved exception.

Before opening the pull request, explicitly verify:

• The branch is based on the current origin/develop.
• VERSION is exactly X.Y.Z.
• The changelog has exactly one vX.Y.Z heading and no [Unreleased].
• No existing tag or release already uses vX.Y.Z.
• The diff contains only release preparation changes.

5. Generate safe release notes

Derive notes from the finalized changelog entry and commits included since the previous release tag. Notes must be useful to repository users and safe for public disclosure.

Remove or generalize:

• Private Azure subscription, tenant, resource group, resource, cluster, registry, vault, endpoint, environment, dashboard, incident, and internal service names.
• Internal aliases, email addresses, customer identifiers, access tokens, secrets, correlation identifiers, and non-public URLs.
• Private work-item links or operational details that expose internal infrastructure.

Preserve public GitHub issue and pull request references when appropriate. Never copy hidden workflow output, credentials, or private Azure names into release notes. If sanitization would make a statement misleading, omit it and flag the omission for human review.

Present the complete sanitized notes for review before publication.