FluidVoice贡献者指南如何提交第一个PR并通过审查【免费下载链接】FluidVoiceFastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows pre-build available! A local Wispr Flow alternative. DM us on X exclusive model access! - https://x.com/fluidvoiceapp项目地址: https://gitcode.com/GitHub_Trending/fl/FluidVoiceFluidVoice 是一款 macOS 上的本地优先语音转文字Dictation应用主打设备端 STT 语音识别与自定义训练的 AI 增强模型是本地版 Wispr Flow 的开源替代方案。本文面向第一次给开源项目提交代码的新手带你走通 FluidVoice 从克隆仓库、本地构建、遵循代码规范到 PR 自动化审查通过的完整贡献流程。贡献流程总览先讨论再动手FluidVoice 的贡献流程有一个明确的特点不是直接开 PR而是先讨论。这一点在 CONTRIBUTING.md 中写得非常清楚提问、提想法、探索设计方向→ 先去 Discussions讨论区发起尤其是 Ideas 分类确认是 Bug→ 提交 Bug Issue必须附上清晰的复现步骤、期望/实际行为、FluidVoice 版本、macOS 版本和架构维护者接受后→ 才正式开 PR且 PR 必须关联已接受的 Issue 或 Discussion 给新手的建议第一次贡献从文档修正或小型 Bug 开始先读几个已合并的 PR了解维护者的审查口味成功率会高很多。环境搭建克隆 FluidVoice 仓库并跑通构建FluidVoice 是一个 Swift Xcode 工程依赖通过 Swift Package Manager 管理不需要额外手动配置第三方库。git clone https://gitcode.com/GitHub_Trending/fl/FluidVoice cd FluidVoice open Fluid.xcodeproj签名配置关键一步打开FluidVoice → Signing Capabilities → Automatically manage signing选择你自己的 Team个人 Team 即可。如果账号有多个 Team 证书可以用环境变量指定其中一个而不改动工程文件FLUIDVOICE_DEVELOPMENT_TEAMYOUR_TEAM_ID ./build.sh运行构建有签名身份./build.sh产物在DerivedData/Build/Products/Debug/FluidVoice Debug.app没有签名身份或模拟 CI./build.sh unsigned本地跑测试xcodebuild test -project Fluid.xcodeproj -scheme Fluid -destination platformmacOS防坑小技巧安装 pre-commit 钩子防止误把个人 Team ID 提交进工程文件这是新手最常见的翻车点cp scripts/check-team-id.sh .git/hooks/pre-commit chmod x .git/hooks/pre-commit该脚本的逻辑很简单一旦检测到project.pbxproj中出现DEVELOPMENT_TEAM变更就拦截提交实现见 scripts/check-team-id.sh。提交前必做格式与代码检查FluidVoice 用SwiftFormat SwiftLint管理代码风格配置分别是 .swiftformat 和 .swiftlint.yml。仓库提供了一个一键脚本 scripts/format-and-lint.sh会自动安装缺失工具并执行./scripts/format-and-lint.sh或者手动执行这也是 CI 使用的检查命令PR 模板里要求你本地跑过swiftformat --config .swiftformat Sources swiftlint --strict --config .swiftlint.yml⚠️ 注意 CI 上 SwiftLint 是--strict模式——本地只是 warning 的问题在 CI 会变成失败。所以提交前必须本地跑一遍不要让 CI 替你发现 lint 错误。填写 PR 模板决定审查生死的细节FluidVoice 有一个PR Policy 自动化检查实现见 .github/workflows/pr-policy.yml 和 .github/policy/enforce-pr-policy.mjs不遵守模板的 PR 会被直接标记失败。模板位于 .github/pull_request_template.md必填项包括模板区块要求Description说明 PR 做了什么、为什么需要Type of Change勾选变更类型Bug fix / 新功能 / 破坏性变更 / 杂项 / 文档Related Issue必须关联 Issue 编号或已接受的 DiscussionTesting说明测试了哪些机型、macOS 版本是否跑过 lint、formatter、测试Screenshots / VideoUI 相关变更必须附截图或录屏无视觉变更则勾选声明框Notes给审查者的补充说明、已知取舍截图要求是硬性的即使你自己勾选了 No UI/visual changes只要改动文件涉及视觉界面PR Policy 工作流仍会检测到并要求截图。下面是一个合格的 UI 变更截图示例来自仓库截图目录两个重要时限缺少必填信息48 小时后 PR 可能被自动关闭不完整的 Bug Issue 如果 14 天内未补充复现信息也可能被关闭理解 CI 审查你的 PR 会经历什么PR 提交后CI 工作流 .github/workflows/build.yml 会依次执行三道关卡变更检测只检查Sources/、Tests/、Package.swift等构建相关文件纯文档 PR 会快速跳过SwiftLint 严格检查在 Docker 中用 swiftlint 0.63.2 执行lint --strictmacOS 构建 全量测试在macos-latest上用最新稳定 Xcode 执行xcodebuild test未签名构建也就是说一个能过审查的 PR 关联 Issue 完整模板 lint 零错误 测试全绿 视觉变更有证据。把这五点做齐基本不会被卡住。新手常见问题Q我想加一个新功能直接写代码然后开 PR 行吗不行。非平凡改动必须先在 Discussion 讨论维护者接受后才动手。这是 FluidVoice 明确的贡献约定。Q一个 PR 可以修多个问题吗不建议。规范是一个 PR 一个功能或修复保持变更原子化、易于审查。Q提交前还要检查什么最后再跑一次git diff确认没有误提交个人 Team ID、API Key 或无关文件。Q测试代码写在哪里单元测试在 Tests/ 目录例如 Tests/HistoryPersistenceBoundaryTests.swift语音转写的集成测试含音频夹具在 Tests/FluidDictationIntegrationTests/资源说明见 Tests/FluidDictationIntegrationTests/Resources/README.md。总结给 FluidVoice 提第一个 PR 的路径是 ——Discussion 先讨论 → 本地构建跑通 → format/lint 全绿 → 完整填写模板并附截图 → CI 三道关卡通过。把流程走顺之后你会发现维护者的审查其实很友好祝你第一个 PR 顺利合并 【免费下载链接】FluidVoiceFastest and only macOS Dictation app with on-device STT and custom trained AI enhancement model. Windows pre-build available! A local Wispr Flow alternative. DM us on X exclusive model access! - https://x.com/fluidvoiceapp项目地址: https://gitcode.com/GitHub_Trending/fl/FluidVoice创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考