agent-desktop/old_docs/RELEASING.md

# Releasing QwenPaw

_中文版：[RELEASING_zh.md](RELEASING_zh.md)_

QwenPaw ships four artifacts from a single version — the **PyPI** wheel, the
**Docker** image, the **desktop** apps (Tauri, Windows + macOS) and the
**plugins** bundle. They are published together by one orchestrated workflow so
that a failure in any one of them blocks the whole release: you can never end up
with, e.g., a web release that has no matching desktop build.

> Orchestrator: [`.github/workflows/release.yml`](.github/workflows/release.yml).
> The older per-artifact workflows are kept as a fallback — see
> [Rollback to the legacy flow](#rollback-to-the-legacy-flow).

## TL;DR

1. Create a **draft** GitHub Release (tag + notes). Do **not** click *Publish*.
2. Actions → **Release (unified)** → *Run workflow* (leave `dry_run` off).
3. It builds + verifies everything; only if all of it passes does it publish all
   artifacts and flip the release to *published*.
4. If anything fails, nothing is published and the draft is left untouched — fix
   and re-run.

## How a release works

`release.yml` runs in three phases:

1. **Resolve** — finds the target draft (the `tag` input, or auto-detects the
   single existing draft), resolves the draft's `target_commitish` to a concrete
   SHA, and pins every downstream job to that SHA (so *what is built* == *what is
   published*). On a real release it also fails fast if the DashScope secret is
   missing.
2. **Prepare** (build + verify, publishes nothing) — in parallel:
   - `build-wheel` — build the Python wheel (with the bundled console).
   - `verify-web` — pip-install, Docker health-check and install-script checks.
   - `build-desktop` — build the Tauri Windows + macOS apps and run the
     install → launch → real-chat UI verification.
   - `build-plugins` — pack the plugin bundle.
3. **Gate + Publish** — every publish job `needs` **all** prepare jobs, so a
   single failure above skips the entire publish phase. When all prepare jobs are
   green: publish to PyPI, push the multi-arch Docker image, attach the desktop
   installers to the release + upload them to OSS, publish plugins — then, as the
   **last** step, flip the draft to *published* (pinned to the built SHA). After
   publishing, it promotes the desktop `latest`/updater, deploys the website
   (stable/post only — betas are skipped), and opens the Release Duty verification
   issue.

A full run is ~60–75 min, dominated by the desktop Tauri builds.

## Cutting a release

1. **Create the draft release**
   - UI: Releases → *Draft a new release* → set the tag + notes → **Save draft**
     (do **not** publish). For a pre-release, tick *Set as a pre-release*.
   - CLI:
     ```bash
     gh release create v2.0.0-beta.8 --draft --prerelease \
       --target main --title "v2.0.0-beta.8" --notes "..."
     ```
   - The tag should correspond to `src/qwenpaw/__version__.py` (`resolve`
     validates this with `packaging` normalization and fails on a mismatch, e.g.
     tag `v2.0.1-beta.1` must match version `2.0.1b1`).
   - Prefer pinning the draft to a commit (`--target <sha>`). If you use
     `--target main`, avoid merging to `main` between creating the draft and
     running the workflow, otherwise the build uses the newer `main` HEAD.
2. **Run the workflow**: Actions → **Release (unified)** → *Run workflow* on
   `main`. Leave `tag` empty to auto-detect the single draft (or set it
   explicitly); leave `dry_run` **unchecked**.
3. **Watch it**: on success the release flips to *published* with all artifacts
   attached and a Release Duty issue is opened. On failure, see
   [Troubleshooting](#troubleshooting).

## Version types: beta / stable / post

The procedure is identical for all types — the type is inferred from the **tag**:

| Type | Example tag | Draft "pre-release"? | Docker tags | PyPI |
|------|-------------|----------------------|-------------|------|
| beta / rc / alpha / dev | `v2.0.0-beta.8` | yes | `<version>` + `pre` (no `latest`) | uploaded; treated as a pre-release by pip (`--pre`) |
| stable | `v2.0.0` | no | `<version>` + `pre` + `latest` | normal |
| post | `v2.0.0.post4` | no | `<version>` + `pre` + `latest` | post release |

Notes:

- Pre-release detection is **tag-based**: a tag containing `beta`/`alpha`/`rc`/`dev`
  is a pre-release (so use the `-beta.N` form); `stable` and `.postN` tags also
  update the Docker `latest` tag.
- The **website** (GitHub Pages, `qwenpaw.agentscope.io`) is deployed only for
  **stable** and `.postN` releases; pre-releases are skipped so the public site
  advertises only GA versions.
- The desktop OSS `latest` files and the Tauri auto-update manifest are currently
  updated for **every** release, including betas (this matches the previous
  `desktop-release.yml` behavior and is unchanged here). Making the desktop
  `latest`/updater stable-only is a possible future improvement.

## Troubleshooting

**Guarantee:** the draft is flipped to *published* only after **all** publish
jobs succeed. If anything fails, the release stays a draft.

| Situation | What happened | What to do |
|-----------|---------------|------------|
| A prepare job fails (desktop / web verify / wheel / plugins) | All publish + `finalize` + `duty-issue` are **skipped**; nothing published; draft untouched | Read the failed job's logs and fix (or re-run if flaky) → **Re-run failed jobs**, or re-run the workflow. No cleanup needed. |
| A publish job fails after the gate (e.g. Docker push fails after PyPI already uploaded) | `finalize` needs all publishes, so the draft is **not** flipped; but some artifacts may already be live | **Re-run failed jobs** (already-succeeded jobs are not re-run; Docker re-push is idempotent, OSS uses `--force`) → the draft flips once they pass. If a published PyPI version is now taken and cannot be reused, cut a `.postN` instead. |
| `finalize` fails | All artifacts published but the release was not flipped | Re-run `finalize`, or manually `gh release edit <tag> --draft=false --target <sha>` (or click *Publish*). |
| `duty-issue` fails | Release is published; only the tracking issue is missing | Re-run the job, or dispatch `release-duty.yml` with the `tag`. Non-blocking. |
| `promote-desktop` fails | Release is published, but the desktop `latest` files / updater manifest / index were not refreshed (existing users' auto-updater does not see the new version yet; versioned downloads still work) | Re-run the job — it is idempotent (`ossutil cp --force`). Non-blocking for first-install users. |
| `deploy-website` fails (stable/post only) | Release is published, but the public site (`qwenpaw.agentscope.io`) still shows the previous version | Re-run the job, or manually dispatch `deploy-website.yml` (workflow_dispatch). Idempotent, non-blocking. |
| "Multiple draft releases found" | More than one draft exists | Re-run *Run workflow* with an explicit `tag`. |
| "No draft release found" / "not a draft" | No draft, or wrong tag | Create the draft / fix the tag, then re-run. |
| resolve rejects the tag (version mismatch) | The draft tag doesn't match `src/qwenpaw/__version__.py` | Align the tag with the version (packaging-normalized, e.g. `v2.0.1-beta.1` ↔ `2.0.1b1`), then re-run. |

## Rollback to the legacy flow

The pre-existing per-artifact workflows are intentionally retained. If the
orchestrator is broken, publish the release the old way — **Publish** the GitHub
Release (or `gh release create ...`), which triggers `publish-pypi` /
`docker-release` / `desktop-release` / `plugins-release` on `release: published`.

> **Warning:** the legacy flow does **not** gate the web release on the desktop
> build (the very problem this orchestrator fixes), so use it only as an
> emergency fallback.

## Fork / dry-run testing

Run **Release (unified)** with `dry_run: true` to exercise the gate and the
draft→published flip **without** touching production: PyPI upload, Docker push
and OSS upload become no-ops, while the desktop build/verify, the draft flip and
the duty issue still run for real. On a fork this only affects the fork's own
release page.

Note: the desktop build's install → launch → chat UI verification still runs
under `dry_run` and needs the `QWENPAW_DASHSCOPE_API_KEY` secret — `dry_run` only
skips the resolve-stage fail-fast check, not the verification itself.