发布流程

所有发布由 Git tag 驱动，CI 自动完成构建和分发。

核心原则：手动打 tag -> 自动构建 -> 自动发布 -> 自动同步。

开发者只需要做一件事：在正确的时机打一个符合规范的 tag。 剩下的构建、打包、发布、跨仓库同步全部由 GitHub Actions 流水线自动完成。

---

第一部分：版本号规范

语义化版本号（SemVer）

格式：MAJOR.MINOR.PATCH（如 0.2.7）

位置	何时递增	示例
MAJOR	不兼容的 API 变更、破坏性改动	0.x.x -> 1.0.0
MINOR	向后兼容的新功能	0.2.x -> 0.3.0
PATCH	向后兼容的 bug 修复	0.2.6 -> 0.2.7

预发布标识附加在版本号后：

• -rc1：发布候选（Release Candidate），功能完整，最终验证阶段
• -beta1：公开测试版，功能基本完整但可能有已知问题
• -alpha1：内部测试版，功能不完整

Tag 命名规范

• 格式：v{MAJOR}.{MINOR}.{PATCH}（如 v0.2.7）
• 预发布：v0.3.0-rc1
• 所有仓库统一使用 v* 前缀

版本号存储位置

仓库	版本号来源	说明
Presto 主应用	Git tag	git describe --tags -> -ldflags 注入，无源文件
模板	manifest.json version 字段	需手动更新后再打 tag
Docker 镜像	自动从 tag 生成	+ . + latest

---

第二部分：Presto 主应用发布

发布前检查清单

• [ ] 所有功能已合并到 main
• [ ] 本地 make build 成功
• [ ] security-scan 无高危漏洞（govulncheck + npm audit）
• [ ] README 已更新（如有新功能）

发布步骤

# 1. 确认当前在 main 分支且代码最新
git checkout main && git pull

# 2. 打 tag
git tag v0.3.0

# 3. 推送 tag（触发 CI）
git push origin v0.3.0

推送 tag 后，CI 自动接管全部后续流程。 详细的流水线 Job 结构和构建矩阵见 CI/CD 流水线文档。

CI 自动执行概览

1. 前端构建（Ubuntu）
2. 多平台并行构建：macOS arm64/amd64（DMG）、Windows amd64/arm64（ZIP）、Linux amd64/arm64（tar.gz）
3. Docker 多架构镜像推送到 GHCR（标签：version + major.minor + latest）
4. 创建 GitHub Release（自动生成 Release Notes + SHA256 checksums）
5. 预发布自动检测：tag 含 -rc/-beta/-alpha 时自动标记为 prerelease
6. 通知 Homepage（repository_dispatch: release-published）

发布后自动同步

• Homepage 自动镜像 Release 并更新下载页版本号（Download.astro + Hero.astro）
• 用户端自动更新检测（应用内检查最新版本）

当前状态：macOS 代码签名需要 Apple Developer Program（$99/年）。 未配置签名 Secrets 时，CI 自动回退到 ad-hoc 签名（-s -）， 用户需执行 xattr -cr Presto.app 绕过 Gatekeeper。

---

第三部分：模板发布

适用于：Starter 仓库和 presto-official-templates。

发布前检查清单

• [ ] make test 全部通过（含安全测试）
• [ ] manifest.json version 字段已更新
• [ ] example.md 能正确转换
• [ ] 在 Presto 中预览效果正确

发布步骤

# 1. 更新 manifest.json 中的 version
# 2. 提交变更
git add manifest.json
git commit -m "chore: bump version to 1.1.0"

# 3. 打 tag 并推送
git tag v1.1.0
git push origin main --tags

CI 自动执行

• 6 平台构建（darwin/linux/windows x arm64/amd64）
• 生成 SHA256SUMS 校验文件
• 通过 softprops/action-gh-release 创建 GitHub Release（自动生成 notes）

详细的构建差异（Go / Rust / TypeScript）见 CI/CD 流水线文档。

官方模板特殊说明

presto-official-templates 是 monorepo 结构，具有智能增量构建能力：

• 只构建有变更的模板子目录
• 共享文件（go.mod、internal/、.github/）变更时构建全部模板
• 一个 tag 可能包含多个模板的更新
• 首次发布或无法检测变更时 fallback 为全量构建

注册中心收录

• 仓库需添加 presto-template topic
• 注册中心 CI 每日 UTC 08:00 扫描（最长 24h 延迟）
• community 信任等级自动收录
• verified 等级需提交 PR 到 template-registry 的 verified-templates.json（当前该文件为空，尚无 verified 模板）

---

第四部分：Changelog 管理

当前方式

所有仓库使用 GitHub 自动生成 Release Notes，无手动维护的 CHANGELOG 文件。

• Presto 主应用：gh release create 配合 --generate-notes
• 模板仓库：softprops/action-gh-release 配合 generate_release_notes: true
• Release Notes 基于 PR 标题和 commit 消息自动生成

建议的 commit 消息规范

为了让自动生成的 Release Notes 更有可读性，建议遵循以下前缀：

前缀	用途	示例
feat	新功能	feat: 支持自定义字体路径
fix	修复	fix: 修复 PDF 导出空白页
chore	维护任务	chore: bump version to 1.1.0
docs	文档更新	docs: 更新安装说明

---

第五部分：跨仓库发布协调

发布依赖关系

关键点

• 各仓库可独立发布，无强制顺序依赖
• 跨仓库同步通过事件驱动异步完成
• 主应用发布后 Homepage 自动同步，无需手动干预
• 模板发布后注册中心在下次 cron 执行时自动收录

认证 Token

Token	用途	配置位置
PRESTO_PAT	跨仓库 API 调用	Organization Secrets
HOMEPAGE_DISPATCH_TOKEN	触发 Homepage 同步工作流	Presto 仓库 Secrets

---

第六部分：故障排除

以下是发布过程中最常见的问题及排查方向。

CI 构建失败

检查 GitHub Actions 日志。常见原因：

• 依赖下载超时（重新运行 Job 通常可解决）
• 平台特定编译错误（检查对应 OS/架构的构建日志）
• 前端构建失败导致后续 Job 全部跳过（先修复前端问题）

macOS 签名相关

当前使用 ad-hoc 签名。CI 中签名步骤为条件性执行： 未配置 APPLE_CERTIFICATE 等 Secrets 时自动跳过正式签名， 回退到 codesign -s - --force --deep。 这不是错误，是预期行为。

Docker 推送失败

• 确认 GITHUB_TOKEN 对 ghcr.io 有 write:packages 权限
• 检查 GHCR 仓库是否存在且可写

Homepage 同步失败

• 检查 PRESTO_PAT 是否过期或权限不足
• 手动触发：到 Homepage 仓库 Actions 页面运行 sync-release.yml

Registry 未收录模板

• 确认仓库已添加 presto-template topic
• 等待下次 cron 执行（每日 UTC 08:00）
• 手动触发：到 template-registry 仓库 Actions 页面运行 update-registry.yml