发布

Tuist 使用持续发布系统，在有意义的变更合并到 main 分支时自动发布新版本。这种方式确保改进能够快速到达用户手中，无需维护者手动干预。

概述

我们持续发布三个主要组件：

• Tuist CLI - 命令行工具
• Tuist Server - 后端服务
• Tuist App - macOS 和 iOS 应用（iOS 应用仅持续部署到 TestFlight，详见此处

每个组件都有自己的发布流水线，每次推送到 main 分支时自动运行。

工作原理

1. 提交约定

我们使用 Conventional Commits 来组织提交消息。这使我们的工具能够理解变更的性质，确定版本号更新，并生成适当的变更日志。

格式：type(scope): 描述

提交类型及其影响

类型	描述	版本影响	示例
feat	新功能或能力	次版本更新 (x.Y.z)	feat(cli): add support for Swift 6
fix	Bug 修复	补丁版本更新 (x.y.Z)	fix(app): resolve crash when opening projects
docs	文档变更	不发布	docs: update installation guide
style	代码风格变更	不发布	style: format code with swiftformat
refactor	代码重构	不发布	refactor(server): simplify auth logic
perf	性能改进	补丁版本更新	perf(cli): optimize dependency resolution
test	测试添加/变更	不发布	test: add unit tests for cache
chore	维护任务	不发布	chore: update dependencies
ci	CI/CD 变更	不发布	ci: add workflow for releases

破坏性变更

破坏性变更会触发主版本更新 (X.0.0)，应在提交正文中说明：

feat(cli): change default cache location

BREAKING CHANGE: The cache is now stored in ~/.tuist/cache instead of .tuist-cache.
Users will need to clear their old cache directory.

2. 变更检测

每个组件使用 git cliff 来：

• 分析自上次发布以来的提交
• 按范围过滤提交（cli、app、server）
• 确定是否有可发布的变更
• 自动生成变更日志

3. 发布流水线

检测到可发布的变更时：

1. 版本计算：流水线确定下一个版本号
2. 变更日志生成：git cliff 从提交消息创建变更日志
3. 构建过程：组件被构建和测试
4. 制品生成：生成特定于发布的资源，如 CLI 包、校验和，以及从 tuist --experimental-dump-help 生成的 tuist.spec.json CLI 规范
5. 发布创建：创建带有制品的 GitHub 发布
6. 分发：更新推送到包管理器（如用于 CLI 的 Homebrew）

4. 范围过滤

每个组件仅在有相关变更时发布：

• CLI：带有 (cli) 范围或没有范围的提交
• App：带有 (app) 范围的提交
• Server：带有 (server) 范围的提交

编写好的提交消息

由于提交消息直接影响发布说明，编写清晰、描述性的消息非常重要：

应该做：

• 使用现在时态：“add feature” 而不是 “added feature”
• 简洁但有描述性
• 变更涉及特定组件时包含范围
• 适当时引用 issue：fix(cli): resolve build cache issue (#1234)

不应该做：

• 使用模糊的消息如 “fix bug” 或 “update code”
• 在一个提交中混合多个不相关的变更
• 忘记包含破坏性变更信息

破坏性变更

对于破坏性变更，在提交正文中包含 BREAKING CHANGE:：

feat(cli): change cache directory structure

BREAKING CHANGE: Cache files are now stored in a new directory structure.
Users need to clear their cache after updating.

发布工作流

发布工作流定义在 .github/workflows/release.yml 中。

它协调 CLI、app、server、cache、Gradle 插件、skills 和 Noora 发布的组件特定作业。对于 CLI，它还生成并发布 tuist.spec.json 制品，以便下游工具可以使用命令接口。

工作流：

• 在推送到 main 时运行
• 使用 git cliff 进行变更检测
• 处理完整的发布过程，包括制品和 GitHub 发布

监控发布

你可以通过以下方式监控发布：

• GitHub Releases 页面
• GitHub Actions 标签页查看工作流运行
• 每个组件目录中的变更日志文件

优势

这种持续发布方法提供：

• 快速交付：变更在合并后立即到达用户
• 减少瓶颈：无需等待手动发布
• 清晰沟通：从提交消息自动生成变更日志
• 流程一致：所有组件使用相同的发布流程
• 质量保证：只有经过测试的变更才会发布

故障排除

如果发布失败：

1. 检查失败工作流的 GitHub Actions 日志
2. 确保你的提交消息遵循约定格式
3. 验证所有测试都通过
4. 检查组件构建成功

对于需要立即发布的紧急修复：

1. 确保你的提交有清晰的范围
2. 合并后监控发布工作流
3. 如有需要，触发手动发布

App Store 发布

虽然 CLI 和 Server 遵循上述持续发布流程，但 iOS 应用由于苹果的 App Store 审核流程是一个例外：

• 手动发布：iOS 应用发布需要手动提交到 App Store
• 审核延迟：每个发布必须经过苹果的审核流程，可能需要 1-7 天
• 批量变更：通常将多个变更捆绑在每个 iOS 发布中
• TestFlight：正式版发布前可通过 TestFlight 分发 Beta 版本
• 发布说明：必须按照 App Store 指南编写

iOS 应用仍然遵循相同的提交约定，并使用 git cliff 生成变更日志，但实际向用户发布的时间安排不那么频繁，属于手动安排。