# ALCOMD3 release workflow

语言: [English](RELEASE.md) | [日本語](RELEASE.ja.md) | 简体中文

这是 ALCOMD3 发布当天的流程。发布由 `xtask` 命令驱动，操作者不再手动修改每一个版本文件。

发布分为三个阶段、两个提交：

1. Source release commit：版本 metadata 和 release notes。
2. GitHub Release：签名后的 Windows installer artifacts。
3. Updater metadata commit：公开 assets 存在后提交 generated updater JSON。

### Version ownership

- Rust 发布版本源：根 `Cargo.toml` 的 `[workspace.package].version`。
- Rust workspace 成员通过 `version.workspace = true` 继承。
- `vrc-get-gui/package.json` 和 `website/package.json` 由
  `cargo xtask release-prepare` 更新。
- `Cargo.lock` 和 `package-lock.json` 是生成文件。
- Updater JSON 由 `cargo xtask release-build` 生成，只能在 GitHub Release assets 公开后提交。

### 1. 确定发布输入

只使用一个 channel。

| Channel | Version example | GitHub Release type | Updater JSON |
| --- | --- | --- | --- |
| Stable | `2.0.1` | normal release | `website/public/api/gui/tauri-updater.json` |
| Beta | `2.1.0-beta.1` | prerelease | `website/public/api/gui/tauri-updater-beta.json` |

在 PowerShell 中设置变量：

```powershell
$Version = "2.0.1"
$Channel = "stable"
```

Stable version 不能包含 prerelease metadata。Beta version 必须包含 prerelease metadata。

### 2. 从 clean state 开始

```powershell
git checkout main
git pull --ff-only
git status --short
gh auth status --hostname github.com
```

预期结果：

- `git status --short` 没有输出。
- GitHub CLI 已对 `CQMHV/ALCOMD3` 完成认证。

如果 worktree 不干净，停止。

### 3. 准备 source release files

```powershell
cargo xtask release-prepare --version $Version --channel $Channel
```

这个命令会：

- 更新 `Cargo.toml` workspace version；
- 刷新 `Cargo.lock` workspace package versions；
- 无 tag 更新 GUI 和 website 的 npm versions；
- 刷新 npm lockfiles；
- 如果不存在则创建 `release-notes/ALCOMD3_$Version.md`；
- 输出 `git status --short`。

现在编辑 release notes 文件，删除所有 placeholder text。

提交并推送 source release commit：

```powershell
git add Cargo.toml Cargo.lock
git add vrc-get-gui/package.json vrc-get-gui/package-lock.json
git add website/package.json website/package-lock.json
git add "release-notes/ALCOMD3_$Version.md"
git status --short
git commit -m "release: prepare ALCOMD3 $Version"
git push origin main
```

这个提交是 GitHub Release tag 应该指向的 source state。它不能包含 generated installer、
`target/`、`artifacts/` 或 updater JSON。

### 4. 构建、签名并验证本地 release artifacts

```powershell
cargo xtask release-build --version $Version --channel $Channel
```

这个命令会：

- 运行 `cargo check` 和 `cargo test`；
- 运行 GUI `npm run lint` 和 `npm run build`；
- 运行 website `npm run check` 和 `npm run build`；
- 构建 Windows installer；
- 构建 installer zip；
- 签名 installer；
- 本地生成所选 channel 的 updater JSON；
- 使用本地 installer 验证 updater JSON；
- 将可发布 artifacts 复制到 `artifacts/release/v$Version/`。

签名优先使用已存在的 `ALCOMD3_UPDATER_PRIVATE_KEY` 和
`ALCOMD3_UPDATER_PRIVATE_KEY_PASSWORD`。如果变量不存在，命令会加载
`artifacts/alcomd3-updater-key/`，优先使用 `private-key.ps1`，否则使用
`private-key.env`。

预期 artifacts：

- `artifacts/release/v$Version/alcomd3-$Version-setup.exe`
- `artifacts/release/v$Version/alcomd3-$Version-setup.exe.sig`
- `artifacts/release/v$Version/alcomd3-$Version-setup.exe.zip`

现在不要提交 updater JSON。GitHub Release 发布前，这个 JSON 指向的 assets 还不是公开资源。

常用检查：

```powershell
cargo xtask release-build --version $Version --channel $Channel --dry-run
cargo xtask release-build --version $Version --channel $Channel --skip-validation
```

只有同一个 source state 已通过验证时，才使用 `--skip-validation`。

### 5. 创建 GitHub Release

创建或刷新 draft：

```powershell
cargo xtask release-publish --version $Version --channel $Channel
```

如果 draft 已存在，并且你明确要替换 assets：

```powershell
cargo xtask release-publish --version $Version --channel $Channel --replace-assets
```

在 GitHub 上检查 notes、assets 和 stable/beta flag。确认无误后发布：

```powershell
cargo xtask release-publish --version $Version --channel $Channel --replace-assets --publish
```

命令会验证 GitHub Release 中存在：

- `alcomd3-$Version-setup.exe`
- `alcomd3-$Version-setup.exe.sig`
- `alcomd3-$Version-setup.exe.zip`

Stable release 不能是 prerelease。Beta release 必须是 prerelease。

### 6. 提交 updater metadata 并构建 website

GitHub Release 公开后：

```powershell
cargo xtask release-updater --version $Version --channel $Channel --commit --push
```

这个命令会：

- 从 GitHub Release 下载 public installer；
- 用下载到的 public installer 验证本地 updater JSON；
- 提交所选 updater JSON；
- 推送 `main`；
- 运行 website `npm run check` 和 `npm run build`；
- 输出部署后需要检查的 public updater endpoint。

如果托管服务自动部署 `origin/main`，等待该 deployment 完成。否则把 `website/dist` 作为
site root 部署。不要直接部署 `website/public`，也不要部署仓库根目录。

### 7. 检查 public updater endpoint

Website deployment 完成后：

```powershell
cargo xtask release-updater --version $Version --channel $Channel --skip-website-build --check-public
```

只有这个 public check 通过，发布才完成。

### Failure rules

以下情况必须停止发布：

- release notes 仍包含 placeholder text；
- validation 失败；
- signing variables 或 signing key loader 缺失；
- artifact 缺失；
- updater JSON verification 失败；
- GitHub Release assets 缺失或命名错误；
- stable/beta flags 错误；
- GitHub Release assets 公开前试图部署 website updater JSON。
