# ALCOMD3 release workflow

言語: [English](RELEASE.md) | 日本語 | [简体中文](RELEASE.zh-CN.md)

これは ALCOMD3 の release-day workflow。Operator が各 version file を手で編集しないよう、
release は `xtask` commands で進める。

Release は 3 phases と 2 commits:

1. Source release commit: version metadata と release notes。
2. GitHub Release: signed Windows installer artifacts。
3. Updater metadata commit: public assets 作成後の generated updater JSON。

### Version ownership

- Rust release version source: root `Cargo.toml` の `[workspace.package].version`。
- Rust workspace members は `version.workspace = true` で継承する。
- `vrc-get-gui/package.json` と `website/package.json` は
  `cargo xtask release-prepare` が更新する。
- `Cargo.lock` と `package-lock.json` は generated files。
- Updater JSON は `cargo xtask release-build` が生成し、GitHub Release assets が
  public になった後だけ commit する。

### 1. Release inputs を決める

Channel は 1 つだけ使う。

| 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
```

Expected result:

- `git status --short` は何も出力しない。
- GitHub CLI が `CQMHV/ALCOMD3` に対して authenticated。

Worktree が dirty の場合は止める。

### 3. Source release files を準備する

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

この command は:

- `Cargo.toml` workspace version を更新する。
- `Cargo.lock` workspace package versions を更新する。
- GUI と website の npm versions を tag なしで更新する。
- npm lockfiles を更新する。
- `release-notes/ALCOMD3_$Version.md` がなければ作成する。
- `git status --short` を表示する。

ここで release notes file を編集し、placeholder text をすべて削除する。

Source release commit を commit/push する:

```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
```

この commit は GitHub Release tag が指す source state。Generated installer、
`target/`、`artifacts/`、updater JSON を含めない。

### 4. Local release artifacts を build、sign、verify する

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

この command は:

- `cargo check` と `cargo test` を実行する。
- GUI `npm run lint` と `npm run build` を実行する。
- Website `npm run check` と `npm run build` を実行する。
- Windows installer を build する。
- Installer zip を build する。
- Installer に署名する。
- 選択した updater JSON を local 生成する。
- Local installer に対して updater JSON を検証する。
- Publishable artifacts を `artifacts/release/v$Version/` に copy する。

Signing は `ALCOMD3_UPDATER_PRIVATE_KEY` と
`ALCOMD3_UPDATER_PRIVATE_KEY_PASSWORD` が設定済みならそれを使う。未設定の場合は
`artifacts/alcomd3-updater-key/` を読み込み、`private-key.ps1` を優先し、
なければ `private-key.env` を使う。

Expected 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 を commit しない。GitHub Release が publish されるまで、その JSON が指す assets は public ではない。

Useful checks:

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

`--skip-validation` は同じ source state で 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 を確認する。問題なければ publish する:

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

Command は 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 を commit し website を build する

GitHub Release が public になった後:

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

この command は:

- GitHub Release から public installer を download する。
- Download 済み public installer に対して local updater JSON を検証する。
- 選択した updater JSON を commit する。
- `main` を push する。
- Website `npm run check` と `npm run build` を実行する。
- Deployment 後に確認する public updater endpoint を表示する。

Hosting provider が `origin/main` を自動 deploy する場合は完了を待つ。そうでない場合は
`website/dist` を site root として deploy する。`website/public` や repository root は
直接 deploy しない。

### 7. Public updater endpoint を確認する

Website deployment 完了後:

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

この public check が通った場合だけ release complete。

### Failure rules

以下の場合は release を止める:

- release notes に placeholder text が残っている。
- validation が失敗する。
- signing variables または signing key loader がない。
- artifact が不足している。
- updater JSON verification が失敗する。
- GitHub Release assets が不足または名前不一致。
- stable/beta flags が誤っている。
- GitHub Release assets が public になる前に website updater JSON を deploy しようとしている。
