Release Process zh HK

Release Process（出 Release）

English version: Release-Process

每個 release 出一個新 DMG，掛喺 tagged GitHub Release。唔使 Apple Developer account——DMG 係 ad-hoc signed，用戶只需要 bypass Gatekeeper 一次。

出 release 前

• 全部 test pass：swift test（v0.4.0 有 157 個）
• App build 得：xcodebuild … CODE_SIGNING_REQUIRED=NO build
• Smoke test（docs/TESTING.md — V0.1 + V0.2 + V0.3 + V0.4 section，至少風險最高嗰幾個 scenario）真機上 pass。
• Release notes draft 好。
• User-visible 行為有改 → README.md + README.zh-HK.md 同步更新。

Version 編號

Setpiece 跟 semver-lite：

• MAJOR：行為顯著唔同（例如 preset 意義變咗）。
• MINOR：新 feature（drag-swap、animation、per-display）。
• PATCH：bug fix only。

V0.4 bundle V0.2 + V0.3 + V0.4 feature → v0.4.0。0.4.0 之上 crash fix → v0.4.1。

喺 SceneApp target 嘅 build settings 改 MARKETING_VERSION（Xcode → SceneApp target → General → Version）。CURRENT_PROJECT_VERSION（build number）可以維持 1。

逐步做（用 v0.4.0 做實例）

# 1. 確保 main 乾淨
git checkout main
git pull
git status   # 一定要 clean

# 2. Xcode 入面 bump version
#    SceneApp target → General → Version：0.4.0
#    Commit："chore: bump version to 0.4.0"

# 3. 重 generate DMG（ad-hoc signed，唔使 Developer ID）
./scripts/build-dmg.sh 0.4.0
#    出 dist/Scene-0.4.0.dmg

# 4. Verify DMG
hdiutil verify dist/Scene-0.4.0.dmg

# 5. Tag + push
git tag -a v0.4.0 -m "Setpiece V0.4.0 — Workspaces, thumbnails, vertical seeds, multilingual UI"
git push origin main
git push origin v0.4.0

# 6. 整 GitHub Release 連 DMG
gh release create v0.4.0 dist/Scene-0.4.0.dmg \
    --title "Setpiece V0.4.0" \
    --notes-file RELEASE_NOTES.md

出 release 嘅慣用一行：

./scripts/build-dmg.sh 0.4.0 && gh release create v0.4.0 dist/Scene-0.4.0.dmg --title "Setpiece V0.4.0" --notes-file RELEASE_NOTES.md

冇 RELEASE_NOTES.md 就用 --notes "..." inline，或者喺 GitHub UI 開 release 手寫 notes。

Release-note template

Setpiece V<x.y.z> — <一句 summary>。

## Install

下載 `Scene-<x.y.z>.dmg`，drag `Scene.app` 去 `/Applications`。第一次 launch：right-click → **Open** bypass Gatekeeper。完整指引 [docs/INSTALL.md](https://github.com/ChiFungHillmanChan/setpiece/blob/main/docs/INSTALL.md)。

## 需求

- macOS 14 (Sonoma) 或以上
- Apple Silicon 或 Intel（universal binary）

## 新功能

- <bullet>

## 修正

- <bullet>

## 已知限制

- <bullet>

出咗 release 之後

• 睇 release 頁 verify：https://github.com/ChiFungHillmanChan/setpiece/releases
• 喺另一部 Mac 下載 DMG 由頭做一次 smoke test。
• 爆 bug：gh release delete <tag> --yes、git tag -d <tag>、git push origin :refs/tags/<tag>。Fix + 重出。

將來有 Apple Developer account 嘅話

由 ad-hoc 轉去正式 Developer ID + notarize：

1. 改 build-dmg.sh 用 CODE_SIGN_IDENTITY="Developer ID Application: Your Name (TEAMID)"。
2. 加 notarize step：

   xcrun notarytool submit dist/Scene-<v>.dmg --apple-id … --team-id … --password … --wait
   xcrun stapler staple dist/Scene-<v>.dmg

3. 用戶就唔使 right-click Open。同步更新 docs/INSTALL.md。