SwiftFormat 项目贡献指南与技术规范解析

SwiftFormat 项目贡献指南与技术规范解析

SwiftFormat A command-line tool and Xcode Extension for formatting Swift code 项目地址: https://gitcode.com/gh_mirrors/sw/SwiftFormat

前言

SwiftFormat 是一个强大的 Swift 代码格式化工具，它能够帮助开发者自动保持代码风格的一致性。本文将深入解析该项目的贡献流程与技术规范，帮助开发者理解如何高效地为该项目做出贡献。

项目行为准则

在参与 SwiftFormat 项目时，所有贡献者都应遵循以下基本原则：

1. 尊重与包容：技术讨论应保持专业和礼貌，任何形式的无礼行为或霸凌都不被容忍
2. 耐心等待：项目维护者可能无法立即响应每个问题或请求，请理解大家都有各自的工作优先级
3. 建设性反馈：即使不同意他人观点，也应提供有建设性的意见而非简单否定

违反这些准则的贡献者可能会被限制参与，无论其技术贡献的价值如何。

版本管理与分支策略

SwiftFormat 采用语义化版本控制(SemVer)原则，但由于目前仍处于1.0之前的阶段，规则相对宽松：

• 0.0.x：用于bug修复和非破坏性变更
• 0.x.0：用于包含破坏性变更的版本

项目维护两个主要分支：

• main：当前发布版本，保持稳定状态
• develop：开发中的下一个版本

这种分支策略确保用户始终能从main分支获取稳定的文档和可执行文件。

代码贡献指南

首次提交建议

初次贡献可能会令人紧张，但请记住：

• 提交请求是协作的开始而非终点
• 即使不完全符合所有指南，也可以先提交再改进
• 对于重大变更，建议先创建讨论议题

提交类型与目标分支

1. 文档修正：针对main分支，包括README或代码注释中的拼写错误
2. 小型代码修复：针对develop分支，如方法名拼写错误等简单修正
3. 重大代码变更：建议先讨论，再向develop分支提交

版权与许可规范

所有新源文件必须包含与现有文件相同的标准许可头。贡献者可以在自己创建或替换的文件中添加自己的名字作为作者。

重要注意事项：

• 不允许包含第三方框架
• 少量兼容许可的代码片段可以包含，但必须注明原始来源
• 提交代码即表示同意按LICENSE.md条款授权

代码风格指南

SwiftFormat 主要遵循Ray Wenderlich风格指南，但有如下例外：

• 使用Xcode默认的4空格缩进
• 注释应遵循"解释为什么，而非做什么"的原则
• 公共方法和类应使用///头文档风格注释

测试要求

所有重要代码变更都应包含相应测试：

1. 单元测试：随代码变更一起提交
2. 性能测试：如果变更可能影响性能，需手动运行性能测试方案
3. 自动化测试：所有提交请求都会自动运行测试套件

规则选项重命名流程

当需要重命名规则选项时，应遵循以下步骤：

1. 在OptionDescriptor.swift的// MARK: - RENAMED部分添加选项副本
2. 为重命名的选项添加.renamed(to: "newPropertyName")
3. 将原始选项的propertyName更新为新名称

发布流程(维护者专用)

完整的发布流程包括：

1. 更新版本号(多个位置)
2. 更新变更日志
3. 更新Podspec文件
4. 运行并确保所有测试通过
5. 归档命令行工具版本
6. 替换CommandLineTool目录中的二进制文件
7. 归档Xcode版本
8. 公证并导出构建的应用
9. 标记提交并推送到main分支
10. 发布Pod版本
11. 构建Windows版本
12. 发布正式版本并附加所有二进制文件
13. 创建并发布Docker镜像

预发布版本使用

对于贡献了新规则或选项的开发者，可以在正式发布前通过预发布构建立即在自己的项目中使用这些新功能。这需要从develop分支构建特定版本。

结语

SwiftFormat 作为一款专业的代码格式化工具，其贡献流程体现了对代码质量和协作规范的重视。理解这些指南将帮助开发者更高效地参与项目，共同提升工具的稳定性和功能性。无论是文档修正、bug修复还是新功能开发，每个贡献都应当遵循项目的技术规范和质量标准。

SwiftFormat A command-line tool and Xcode Extension for formatting Swift code 项目地址: https://gitcode.com/gh_mirrors/sw/SwiftFormat