# Phát hành Oleafly

Dựng một bản nháp hoàn chỉnh từ một thẻ phiên bản, soát từng artifact của mỗi nền tảng, rồi phát hành qua workflow phát hành có kiểm soát.

Quá trình phát hành Oleafly có hai giai đoạn chủ đích. Một thẻ phiên bản dựng và kiểm chứng một bản nháp. Một người bảo trì phát hành chính bản nháp đó bằng một lần chạy workflow riêng.

Đẩy code lên `main` sẽ chạy CI nhưng không tạo bản phát hành.

## Dựng bản nháp

Bắt đầu từ nhánh `main` mới nhất với CI xanh.

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

Thẻ đó kích hoạt `.github/workflows/release.yml`. Workflow dựng các target sau:

| Target | Bộ cài đặt |
|---|---|
| macOS Apple Silicon | `.dmg` |
| Windows x64 | `.msi` và `-setup.exe` |
| Linux x64 | `.AppImage` và `.deb` |
| Linux ARM64 | `.AppImage` và `.deb` |

Mỗi target tải về và xác minh các sidecar trình biên dịch đã ghim của nó. Workflow sau đó gộp cả bốn mảnh updater thành một `latest.json`. Bản nháp chỉ được coi là sẵn sàng khi mọi mục bộ cài đặt và updater bắt buộc đều có mặt.

## Soát lại bản nháp

Mở bản nháp trên [trang GitHub Releases](https://github.com/Oleafly/Oleafly/releases). Kiểm tra ghi chú phát hành, tên bộ cài đặt, checksum, chữ ký và `latest.json`. Đừng phát hành một bản nháp chưa đầy đủ.

## Phát hành

Mở **Actions → Release → Run workflow**. Nhập thẻ đã dùng và chọn **Publish the release**.

Lần chạy phát hành lặp lại các bước dựng và kiểm tra artifact. Nó còn chạy các contract test trực tiếp với Anthropic và Google bằng bản ứng viên phát hành. Job cuối cùng từ chối phát hành trừ khi mọi nền tảng được hỗ trợ và nguồn cập nhật updater đầy đủ đều hiện diện.

Việc phát hành làm `latest.json` hiển thị với các ứng dụng đã cài. Hãy coi đó là một thao tác sản xuất không thể hoàn tác. Nếu lần chạy phát hành thất bại, hãy giữ bản phát hành ở dạng nháp, sửa nguyên nhân, rồi chạy lại.

## Số hiệu phiên bản

Oleafly theo phiên bản hóa ngữ nghĩa:

- **Patch**, chẳng hạn từ `0.3.5` lên `0.3.6`, cho các bản sửa tương thích.
- **Minor**, chẳng hạn từ `0.3.5` lên `0.4.0`, cho các tính năng tương thích.
- **Major**, chẳng hạn từ `0.3.5` lên `1.0.0`, cho các thay đổi phá vỡ tương thích hoặc bản phát hành ổn định đầu tiên.

## Các kiểm tra quan trọng

- Thẻ phải khớp với `package.json`, `src-tauri/tauri.conf.json`, `src-tauri/Cargo.toml` và `src-tauri/Cargo.lock`. Dùng `scripts/bump-version.sh` thay vì sửa từng tệp riêng.
- Ghi chú phát hành lấy từ mục phiên bản tương ứng trong `CHANGELOG.md`.
- Đừng tái sử dụng một thẻ đã phát hành. Với một bản nháp thất bại, hãy sửa nhánh và tạo phiên bản mới, trừ khi có lý do rõ ràng để thay thế thẻ chưa phát hành.
- Việc ký và notarization trên macOS dùng các secret phát hành của Apple. Authenticode trên Windows dùng Azure Artifact Signing khi các secret của nó đã được cấu hình. Chữ ký updater dùng khóa ký Tauri riêng.

Xem [Tự động cập nhật](/docs/engineering/updates/) về cách ký updater và hành vi quay lui. Hướng dẫn cài đặt cho người dùng nằm ở [Tải về và cài đặt](/docs/install/).