# 发布 Oleafly

从版本标签构建完整的草稿，逐一检查各平台的产物，再通过受保护的发布工作流正式发布。

Oleafly 的发布分为两个有意为之的阶段。版本标签会构建并验证一份草稿。维护者再用另一次工作流运行来发布这份草稿。

推送到 `main` 会运行 CI，但不会创建发布。

## 构建草稿

从最新的 `main` 分支开始，并确保 CI 全部通过。

```sh
git switch main
git pull --ff-only
./scripts/bump-version.sh 0.3.6
git commit -am "chore: release v0.3.6"
git push origin main
git tag v0.3.6
git push origin v0.3.6
```

该标签会触发 `.github/workflows/release.yml`，它会构建以下目标：

| 目标 | 安装包 |
|---|---|
| macOS Apple Silicon | `.dmg` |
| Windows x64 | `.msi` 和 `-setup.exe` |
| Linux x64 | `.AppImage` 和 `.deb` |
| Linux ARM64 | `.AppImage` 和 `.deb` |

每个目标都会获取并验证它固定版本的编译器 sidecar。随后工作流把四份更新程序片段合并成一个 `latest.json`。只有当每个必需的安装包和更新条目都齐备时，这份草稿才算准备就绪。

## 检查草稿

打开 [GitHub Releases 页面](https://github.com/Oleafly/Oleafly/releases)上的草稿。检查发布说明、安装包名称、校验和、签名以及 `latest.json`。不要发布不完整的草稿。

## 发布

打开 **Actions → Release → Run workflow**。输入同一个标签，并选择 **Publish the release**。

发布运行会重复构建和产物检查。它还会使用候选发布版对 Anthropic 和 Google 运行真实的契约测试。除非所有受支持的平台和完整的更新源都已就绪，否则最后一个任务会拒绝发布。

发布后，已安装的应用就能看到 `latest.json`。请把它当作不可逆的生产操作。如果发布运行失败，让发布保持草稿状态，修复原因后再次运行。

## 版本号

Oleafly 遵循语义化版本：

- **补丁版本**，例如 `0.3.5` 到 `0.3.6`，用于兼容的修复。
- **次版本**，例如 `0.3.5` 到 `0.4.0`，用于兼容的新功能。
- **主版本**，例如 `0.3.5` 到 `1.0.0`，用于破坏性变更或第一个稳定版本。

## 重要检查

- 标签必须与 `package.json`、`src-tauri/tauri.conf.json`、`src-tauri/Cargo.toml` 和 `src-tauri/Cargo.lock` 一致。请使用 `scripts/bump-version.sh`，不要分别手动修改这些文件。
- 发布说明来自 `CHANGELOG.md` 中对应版本的章节。
- 不要复用已发布的标签。草稿失败时，修复分支并创建新版本，除非有明确理由替换尚未发布的标签。
- macOS 的签名和公证使用 Apple 发布密钥。配置了相应密钥时，Windows 的 Authenticode 使用 Azure Artifact Signing。更新程序签名使用单独的 Tauri 签名密钥。

更新程序签名与回滚行为参见[自动更新](/docs/engineering/updates/)。面向用户的安装说明在[下载与安装](/docs/install/)。