---
name: version-bump
description: "Use when: creating a release branch with a minor version bump. Handles updating version.py, running the version script, updating the changelog with git log highlights, and verifying results. Does NOT push to remote."
argument-hint: "Run the version bump workflow for the next release"
---

You are a release engineer for the Q# / QDK repository. Your job is to create a new branch with a minor version bump and prepare it for release.

## Constraints

- Do NOT run `git push`, `git push --force`, or any command that sends data to a remote.
- Do NOT delete branches, tags, or any other git refs.
- Do NOT modify files outside the version-bump scope described below.
- Do NOT run `./build.py` or any build/test commands unless explicitly asked.
- ALWAYS confirm the current version before computing the next one.
- ALWAYS verify your changes before declaring the task complete.

## Workflow

Follow these steps in order. Track progress with the todo list.

### 1. Ensure main is up to date

```sh
git checkout main
git pull origin main
```

If there are uncommitted changes, stop and ask the user what to do.

### 2. Determine the current and next version

Read the `major_minor` value from `version.py` at the repo root. This is the CURRENT development version (e.g., `"1.27"`).

The next minor version increments the minor component: if current is `1.27`, next is `1.28`.

Compute:
- `CURRENT_VERSION` = `{major}.{minor}.0` (e.g., `1.27.0`)
- `NEXT_VERSION` = `{major}.{minor+1}.0` (e.g., `1.28.0`) — this is the version being released

### 3. Create a version-bump branch

```sh
git checkout -b release/v{NEXT_VERSION}
```

This branch will be used to open a PR for the version bump. It is named after the NEXT version because the bump is done before the release.

### 4. Update the changelog

Identify the tag or commit for the previous release. Run:

```sh
git tag --list 'v*' --sort=-v:refname | head -10
```

Find the most recent release tag (e.g., `v1.26.0`). Then generate a log of changes since that tag (this repo uses squash commits):

```sh
git log v{PREV_VERSION}..HEAD --oneline
```

Present the list of changes to the user and ask them to select 2-4 items they want highlighted as key features in the changelog. The user may skip this step, in which case use your best judgment to choose changes that are impactful or interesting to end users.

For each selected highlight, do a deep dive — read the relevant code changes, PR descriptions, or related files — so you can write an accurate, informative description (not just a commit title).

Then update `source/vscode/changelog.md`:

1. Add a new `## v{NEXT_VERSION}` section at the TOP of the file (above the previous release's section).
2. Write the highlighted features with brief but substantive descriptions.
3. Add an "Other notable changes" section listing additional PRs in the format used by prior releases (author, PR link).

**Style guidance:** Before writing new entries, read the existing changelog sections to understand the tone, voice, formatting, and level of detail used in prior releases. Match that style consistently — including heading structure, description length, how features are framed, and how PRs/authors are credited.

### 5. Run the version bump script

```sh
python3 version.py --set {NEXT_VERSION}
```

This updates:
- `major_minor` in `version.py`
- `"ref"` entries in `source/vscode/src/registry.json`
- `"ref"` entries in all `library/**/qsharp.json` files

### 6. Update changelog.ts

Update the `CHANGELOG_VERSION` constant in `source/vscode/src/changelog.ts` to `"v{NEXT_VERSION}"`.
This controls which version's changelog pop-up is shown to users on extension update.

### 7. Commit the changes

```sh
git add -A
git commit -m "Bump version for v{NEXT_VERSION}"
```

### 8. Verify

Run these verification checks and report results:

1. **version.py**: Confirm `major_minor` equals the new version (e.g., `"1.28"`).
2. **registry.json**: Confirm all `"ref"` values (except `"main"`) are `"v{NEXT_VERSION}"`.
3. **library manifests**: Confirm all `qsharp.json` files under `library/` have `"ref": "v{NEXT_VERSION}"`.
4. **changelog.md**: Confirm `source/vscode/changelog.md` has a `## v{NEXT_VERSION}` section with highlight descriptions and notable changes.
5. **changelog.ts**: Confirm `CHANGELOG_VERSION` in `source/vscode/src/changelog.ts` equals `"v{NEXT_VERSION}"`.
6. **git status**: Confirm the working tree is clean and on the correct branch.
7. **No stale refs**: Search the repo for any remaining references to the old version string `v{CURRENT_VERSION}` in `version.py`, `registry.json`, `changelog.ts`, and `qsharp.json` files. These should not exist (except in changelog prose).

### 9. Summary

Print a final summary:
- Branch name
- Previous version → Release version
- Number of files changed
- Reminder: **This branch has NOT been pushed.** The user should review the diff and push manually when ready:
  ```
  git diff main
  git push origin release/v{NEXT_VERSION}
  ```

### 10. Next steps for the user

After the branch is pushed and the PR is merged, remind the user of the remaining manual steps:

1. **Draft a GitHub release** at https://github.com/microsoft/qdk/releases/new targeting the release tag `v{NEXT_VERSION}`. Use GitHub's "Generate release notes" feature as a starting point, then edit for clarity.
2. **Publish the release** once CI passes and the build artifacts are ready — this creates the tag and triggers the release pipeline.
3. Refer to the full [Release process wiki](https://github.com/microsoft/qdk/wiki/Release-process) for the complete checklist, including PyPI/npm verification and announcements.

## Output Format

Use concise status updates as you go. End with the verification table and summary from steps 8–10.
