RELEASING.md

Photo Insight 发布指南

本文描述 v1.x 的标准 GitHub 发布流程。普通本地开发不需要 Developer ID 或 Apple 公证。

1. 发布前检查

1. 工作区没有无关修改。
2. AppResources/Info.plist 中版本号与准备创建的 Tag 一致。
3. CHANGELOG.md 已记录用户可见变化。
4. 所有测试、应用构建和发布文件检查通过：

swift test --disable-sandbox
BUILD_ARCHS=native ./scripts/build-app.sh
./scripts/check-publication.sh

2. 本地签名和公证

需要 Apple Developer Program、有效的 Developer ID Application 证书，以及 notarytool 凭据。

先把公证凭据保存到钥匙串：

xcrun notarytool store-credentials "photo-insight-notary"

然后生成 Universal、签名、公证并附加票据的发布包：

SIGNING_IDENTITY="Developer ID Application: Your Name (TEAMID)" \
NOTARY_PROFILE="photo-insight-notary" \
./scripts/package-release.sh --notarize

检查最终应用：

./scripts/verify-release.sh

产物位于 release/，包括版本化 ZIP 和 SHA-256 文件。不要把证书、私钥、API Key 或发布包提交到源码仓库。

3. GitHub Actions 所需 Secrets

自动 Release 工作流需要在仓库 Settings → Secrets and variables → Actions 中配置：

Secret	内容
BUILD_CERTIFICATE_BASE64	Developer ID .p12 文件的 Base64
P12_PASSWORD	.p12 导出密码
KEYCHAIN_PASSWORD	CI 临时钥匙串使用的随机密码
DEVELOPER_ID_APPLICATION	完整签名身份名称
APPLE_API_KEY_BASE64	App Store Connect API .p8 文件的 Base64
APPLE_API_KEY_ID	API Key ID
APPLE_API_ISSUER_ID	App Store Connect Issuer ID

在 macOS 上可使用以下方式编码文件：

base64 -i DeveloperID.p12 | pbcopy
base64 -i AuthKey_XXXXXXXXXX.p8 | pbcopy

4. 创建正式版本

合并所有发布准备后，创建并推送带注释 Tag：

git tag -a v1.1.0 -m "Photo Insight v1.1.0"
git push origin main
git push origin v1.1.0

配置好 Developer ID 和公证 Secrets 后，在 GitHub Actions 中手动运行 Signed macOS release，并填写已存在的 Tag。签名工作流不再由 Tag 自动触发， 避免尚未配置 Apple 凭据时产生失败的发布任务。

不要在同一 Tag 上替换安装包。需要修复时提高版本号并创建新 Tag。

5. 发布后验证

• 在一台没有开发证书的 Mac 上从 GitHub Release 下载 ZIP。
• 校验 SHA-256，解压并确认 Gatekeeper 正常显示开发者身份。
• 验证首次启动、目录授权、三种扫描预设、自定义扫描方案、扫描预览、索引、地图、导出和中英文切换。
• 确认官网“下载”按钮指向最新 Release。
• 创建 GitHub Release 后再更新 README 中的可用状态。

6. GitHub Pages

仓库创建后，在 Settings → Pages → Build and deployment 中把 Source 设为 GitHub Actions。pages.yml 会在 docs/ 变化并推送到 main 时自动部署官网。