我们欢迎每个人为 Swift 做出贡献。 参与贡献并不仅仅意味着提交拉取请求（Pull Request）—— 您可以通过多种不同的方式参与其中， 包括在论坛上回答问题、 报告或分类错误、以及参与 Swift 演进过程。

无论您想以何种方式参与， 我们都希望您首先通过阅读社区概览 了解项目参与者应遵循的准则。 如果您要贡献代码，您还应该了解如何从代码库中 构建和运行 Swift， 具体说明请参见源代码。

解答问题

在社区中提供支持最重要和最直接的方式之一，就是在论坛上解答问题。无论是帮助新手理解某个语言特性，还是与经验丰富的开发者一起排查疑难问题，您的 Swift 知识和经验都能为他人提供很大帮助。

报告 Bug

报告 Bug 是任何人都可以帮助改进 Swift 的好方法。开源 Swift 项目使用 GitHub Issues 来跟踪 Bug。

在创建 issue 时，请包含以下内容：

• 问题的简明描述。 如果是崩溃问题，请包含堆栈跟踪信息。否则，请描述您期望看到的行为以及实际观察到的行为。

• 可复现的测试用例。 请再次确认您的测试用例能够复现该问题。对于相对较小的示例（大约 50 行代码以内），最好直接粘贴到描述中；较大的示例可以作为附件上传。请考虑将示例精简到尽可能少的代码——更小的测试用例更容易理解，也更容易吸引贡献者关注。

• 复现问题的环境描述。 包括 Swift 编译器的版本、部署目标（如果明确设置）以及您的平台信息。

由于 Swift 正在积极开发中，我们会收到大量的 Bug 报告。在创建新的 issue 之前，请花点时间浏览我们现有的 issues，以减少重复报告的可能性。

问题分类处理

报告问题是改进软件的重要组成部分。 同样重要的是对这些问题进行分类处理， 以确保它们是可复现的、简明的且不重复的。

在问题追踪系统中， 你可以通过以下几种方式来帮助进行问题分类：

• 复现问题。 要使一个问题具有可操作性， 首先需要能够复现它。 如果你无法复现某个问题， 请尝试找出原因。 如果需要更多信息，请与提交者联系。

• 简化问题。 一旦问题可以被复现， 就将其简化到最少的代码量。 分析一个只需几行 Swift 代码就能复现的问题， 要比分析一个较长的代码示例容易得多。

• 消除重复问题。 如果两个问题报告指向同一个潜在问题， 请将较新的标记为较旧问题的重复项。 这样做可以帮助其他人更有效地工作。

网站和博客文章贡献

Swift 项目欢迎对本网站的建议和改进，以及展示社区各项倡议和故事的社区博客文章投稿。Swift 网站工作组负责监督所有网站和博客文章的贡献。

您可以在 Swift.org 网站管理流程中了解更多关于为本网站做贡献的信息，以及如何提交博客文章投稿。

Swift 演进

塑造 Swift 的未来是一项社区努力，任何人都可以通过 Swift 论坛的演进版块参与其中。 Swift 演进流程涵盖了 Swift 语言和 Swift 标准库公共接口的所有变更，包括新的语言特性和 API、对现有语言特性或 API 的修改、移除现有特性等。

查看 Swift 演进评审计划 了解当前和即将进行的提案评审。

新手友好议题

新手友好议题是指那些适合 Swift 项目新手，甚至是对 Swift 编译器等子项目的模式和概念还不熟悉的贡献者参与的 bug、想法和任务。新手友好议题会标注相应的标签，最简单的查找方式是访问 github.com/apple/<仓库名>/contribute，例如 Swift 主仓库的地址是 github.com/apple/swiftlang/contribute。这些议题通常优先级较低，范围适中，不需要过多的重构、研究或调试——相反，它们旨在鼓励新人接触 Swift 的某个部分，了解更多相关知识，并做出实际贡献。

任何拥有提交权限且对特定领域有深入了解的人都欢迎并鼓励去确定或构思新手友好议题。

贡献代码

入门指南

在直接为 Swift 语言本身做贡献之前，强烈建议你先在自己的项目中熟悉使用 Swift。我们准备了详细的入门指南，提供了分步说明来帮助你快速上手。

渐进式开发

Swift 项目采用小型、渐进式的变更作为其首选的开发模式。有时这些变更是小的错误修复。其他时候，这些变更是实现更大目标道路上的小步骤。相比之下，长期开发分支可能会导致社区在开发过程中失去发言权。长期分支还存在以下一些问题：

• 如果分支开发和主线开发在相同的代码部分进行，解决合并冲突可能会花费大量时间。
• 社区成员往往会忽视分支上的工作。
• 非常大的变更很难进行代码审查。
• 分支不会被持续集成基础设施定期测试。

为了解决这些问题，Swift 采用渐进式开发风格。在可能的情况下，优先选择小的变更。我们要求贡献者在进行大型或具有侵入性的变更时遵循这种做法。以下是一些建议：

• 大型或侵入性变更通常需要在主要变更之前进行一些次要变更（例如，API 清理或添加）。在进行主要变更之前，独立提交这些变更。

• 如果可能，将剩余的相互关联的工作分解为互不相关的变更集。然后，定义第一个增量并就变更的开发目标达成共识。

• 使变更集中的每个变更要么是独立的（例如，修复错误），要么是朝着开发目标前进的计划系列变更的一部分。向社区解释这些关系会很有帮助。

如果你想进行大型变更但对其整体影响感到不确定，请务必先通过开发者论坛讨论变更并达成共识。然后询问如何最好地进行这个变更。

提交信息

虽然我们不强制要求特定的提交信息格式，但我们建议你遵循以下在开源项目中常见的指导原则。遵循这些指导原则有助于代码审查过程、搜索提交日志和邮件格式化。从高层次来看，提交信息的内容应该传达变更的理由，而不需要深入太多细节。例如，”位没有设置正确”让审查者不清楚是哪些位以及为什么它们不”正确”。相比之下，”在’Type’中正确计算’is dependent type’位”几乎传达了变更的全部内容。

以下是关于提交信息格式本身的一些指导原则：

• 将提交信息分为单行标题和描述变更的单独正文。
• 使标题简洁，以便在提交日志中易于阅读，并适合作为提交邮件的主题行。
• 在仅限于代码特定部分的变更中，在行首用方括号包含[标签]—例如，”[stdlib] …“或”[SILGen] …“。这个标签有助于邮件过滤和提交后审查的搜索。
• 当有正文时，用空行将其与标题分开。
• 使正文简洁，但包含完整的推理。除非理解变更需要，否则额外的代码示例或其他细节应留在错误评论或邮件列表中。
• 如果提交修复了错误跟踪系统中的问题，在信息中包含该问题的链接。
• 对于文本格式和拼写，遵循与文档和代码内注释相同的规则—例如，大写字母和句号的使用。
• 如果提交是在另一个最近提交的变更之上的错误修复，或者是补丁的还原或重新应用，请包含先前相关提交的 Git 修订号，例如”还原 abcdef，因为它导致 bug#”。

对于这些指导原则的轻微违反，社区通常倾向于提醒贡献者这个政策，而不是还原。小的更正和遗漏可以通过向提交邮件列表发送回复来处理。

变更归属

当贡献者向 Swift 子项目提交变更时，在该变更被批准后，其他具有提交权限的开发者可以代表作者提交。这样做时，保持正确的贡献归属很重要。一般来说，Git 会自动处理归属。

我们不希望源代码中充斥着像”此代码由 J. Random Hacker 编写”这样随意的归属，这会造成干扰和分散注意力。不要在源代码或文档中添加贡献者姓名。

此外，除非他人已向项目提交了变更，或者你已获得代表他们提交的授权（例如，你们一起工作，你的公司授权你贡献这些变更），否则不要提交他人编写的变更。作者应该首先通过向相关项目提交拉取请求、向开发邮件列表发送邮件或添加错误跟踪器项目来提交变更。如果有人私下向你发送变更，请鼓励他们首先将其提交给适当的列表。

代码模板

如社区概述中所述，Swift.org 代码的许可证和版权保护在每个源代码文件的顶部都有说明。在极少数情况下，如果你贡献的变更包含新的源文件，请确保适当填写头部信息。

对于 Swift 源文件，代码头部应该如下所示：

//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//

对于 C 或 C++ 源文件或头文件，代码头部应该如下所示：

//===-- subfolder/Filename.h - Very brief description -----------*- C++ -*-===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
//===----------------------------------------------------------------------===//
///
/// \file
/// This file contains stuff that I am describing here in the header and will
/// be sure to keep up to date.
///
//===----------------------------------------------------------------------===//

分隔线应该正好是 80 个字符宽，以帮助遵守代码风格指南。底部部分包含用于生成文档的可选描述（这些行以 /// 开头，而不是 //）。如果没有描述，可以跳过这个区域。

发布分支拉取请求

针对发布分支（release/x.y 或 swift/release/x.y）的拉取请求在没有相应分支管理员的 GitHub 批准的情况下不能合并。为了使变更被考虑纳入发布分支，拉取请求必须：

• 标题以包含目标分支发布版本号的标识开头。

• 在其描述中填写此表单。不适用的项目可以留空或填写相应说明，但不能完全省略。

  在浏览器中为 swiftlang 仓库起草拉取请求时，要切换到此模板，请在当前 URL 后附加 template=release.md 查询参数并刷新。 例如：

  -https://github.com/swiftlang/swift/compare/main...my-branch?quick_pull=1
  +https://github.com/swiftlang/swift/compare/main...my-branch?quick_pull=1&template=release.md
  

这里是一个示例。

代码审查

Swift 项目严重依赖代码审查来提高软件质量：

• 所有开发者进行的所有重要变更在提交到仓库之前都必须经过审查。较小的变更（或开发者拥有组件的变更）可以在提交后进行审查。
• 代码审查在 GitHub 上进行（通过对拉取请求或提交的评论），并反映在相关项目的提交邮件列表中。
• 负责代码变更的开发者也负责进行所有必要的与审查相关的更改。

代码审查可以是一个迭代过程，持续到变更准备好提交为止。在变更发送出去审查后，在提交之前需要明确的批准。不要假设默许批准或通过设置截止日期来请求对补丁的主动反对。

有时代码审查可能需要比你希望的时间更长，特别是对于较大的功能。以下是一些加快补丁审查时间的公认方法：

• 审查其他人的变更。 如果你帮助他人，每个人都会更愿意为你做同样的事情。善意是我们的货币。
• 将你的变更拆分为多个较小的变更。 变更越小，有人快速查看它的可能性就越高。
• 提醒变更。 如果很紧急，提供为什么尽快落地这个变更很重要的原因，并每隔几天提醒一次。如果不紧急，通常的礼貌提醒频率是一周一次。记住，你是在请求其他专业开发者的宝贵时间。

请注意，任何人都可以审查和提供关于变更的反馈，但只有对仓库有提交权限的人才能批准它。

测试

开发者需要为任何修复的错误和添加的新功能创建测试用例，并将它们与变更一起贡献。

• 所有功能和回归测试用例都添加到适当的测试目录中—例如，swift/test 目录。
• 在最接近实际功能的抽象级别编写测试用例。例如，如果是 Swift 语言功能，用 Swift 编写；如果是 SIL 优化，用 SIL 编写。
• 尽可能减少测试用例，特别是对于回归测试。将整个失败的程序放入 swift/test 是不可接受的，因为这会使所有开发者的测试变慢。请保持它们简短。

质量

人们依赖 Swift 来创建他们的生产软件。这意味着 Swift 中的错误可能会导致数千甚至数百万开发者的产品出现错误。因此，Swift 项目对质量保持高标准。任何变更在提交到主开发分支之前必须满足的最低质量标准包括：

1. 代码必须至少在一个平台上编译时没有错误或警告。
2. 错误修复和新功能必须包含测试用例以确定任何未来的回归，或包含为什么测试用例不切实际的理由。
3. 代码必须通过适当的测试套件—例如，Swift 编译器中的 swift/test 和 swift/validation-test 测试套件。

此外，提交者负责解决变更可能在未来造成的任何问题。这种责任意味着你可能需要更新你的变更以：

• 确保代码在所有主要平台上都能干净地编译。
• 修复在其他测试套件中发现的任何正确性回归。
• 修复任何重大性能回归。
• 修复下游 Swift 工具中的任何性能或正确性回归。
• 修复使用 Swift 的客户代码中出现的任何性能或正确性回归。
• 解决由于你的变更而在错误跟踪器中出现的任何错误。

我们更希望这些问题在提交之前得到处理，但我们理解不可能对每个提交都测试所有这些。我们的持续集成（CI）基础设施通常会找到这些问题。我们建议在接下来的日子里关注 CI 基础设施以寻找回归。如果包含你的提交的一组提交导致了失败，CI 基础设施会直接给你发邮件。你应该检查这些消息，看看它们是否是你的问题，如果是，修复这个破坏。

明显违反这些质量标准的提交可能会被还原，特别是当变更阻止其他开发者取得进展时。在问题修复后，开发者可以重新提交变更。

贡献者阶梯

这个贡献者阶梯定义了你在为 GitHub 上的 Swift 做贡献时可能获得的角色。每个角色都有相关的特权，这需要与贡献者社区建立信任。我们认识到 Swift 有许多不同类型的贡献者，我们感谢每一个！每个参与开源 Swift 项目的人都是贡献者：这可以是编写代码、在论坛上回答问题、报告或分类错误，或参与 Swift 演进过程。

当你通过为 GitHub 上的 Swift 做贡献而攀登贡献者阶梯时，你获得新的特权，但也获得了信任和责任，你被期望履行这些责任。如果贡献者违反这种信任和责任，核心团队可能会给他们通知，并在重复违规时撤销他们的级别。我们相信一个健康的社区，并希望这种行动永远不会是必要的。

成员

成员已经多次为 Swift 做出了建设性的贡献。这个角色在整个组织中持有，成为成员允许你在 GitHub 上的 swiftlang 组织中的所有仓库触发 CI。

• 要求
  • 对 Swift 项目做出多次建设性的贡献。这可以是 PR 的形式、参与 Swift 论坛、提交有价值的议题、对它们进行分类，或类似的形式。
• 特权
  • 能够触发 CI 测试
  • 在你的 GitHub 个人资料上显示你在 swiftlang 组织中的成员身份
• 提名
  • 如果你想成为成员，请发送一封电子邮件到代码所有者列表，包括你的贡献和你想要使用的 GitHub 用户名
• 成长
  • 展示你建设性地使用特权并继续贡献以获得提交权限。

提交权限

提交权限授予给有提交高质量变更记录的贡献者。如果你想获得提交权限，请发送一封电子邮件到代码所有者列表，包括你想要使用的 GitHub 用户名和 5 个被接受且无需修改的非平凡拉取请求的列表。

一旦你被授予提交权限，你将能够提交到所有托管 Swift.org 项目的 GitHub 仓库。要验证你的提交权限是否有效，请进行一个测试提交（例如，更改注释或添加空行）。以下政策适用于具有提交权限的用户：

• 你被授予对 Swift 所有部分的批准后提交权限。要获得批准，创建拉取请求。当拉取请求被批准时，你可以自己合并它。

• 你可以在不首先获得批准的情况下提交明显的变更。社区期望你使用良好的判断力。例子包括还原明显损坏的补丁、更正代码注释和其他小变更。

• 你被允许在没有批准的情况下提交变更到你已贡献或已被分配责任的 Swift 部分。此类提交不得破坏构建。这是一个”信任但验证”的政策，这种性质的提交在提交后会被审查。

多次违反这些政策或一次严重违反可能导致提交权限被撤销。即使有提交权限，你的变更仍然需要经过代码审查。当然，我们也鼓励你审查其他人的变更。

代码所有者

代码所有者是被分配到 Swift 项目特定领域的个人，他们的主要职责是代码质量。Swift 项目由许多子项目组成，包括 Swift 标准库、LLDB 调试器的扩展和 Swift 包管理器等。每个子项目都会被分配一个代码所有者。代码所有者然后努力让所有贡献得到审查，收集社区的反馈，并将批准的补丁引导到产品中。

任何人都可以审查一段代码，我们欢迎所有感兴趣的人进行代码审查。代码审查程序不是由中央、全局政策决定的。相反，这个过程由每个代码所有者定义。

任何活跃并证明自己有价值的社区成员都可以通过发帖到论坛来提供成为代码所有者，或被另一个成员提名。如果其他贡献者同意，项目负责人将做出任命并将新所有者的名字添加到代码所有者文件中。这个职位完全是自愿的，可以随时辞职。

当前代码所有者的列表可以在父 Swift 源代码树的根目录中的 CODE_OWNERS.txt 文件中找到。我们还维护一个邮件组，这样你可以发送电子邮件给所有代码所有者。

对于 Swift 的成功来说，可能没有什么比强大、投入的代码所有者更重要了。我们都欠他们尊重、感激和任何我们能提供的帮助。

每个贡献者都有责任将自己的名字添加到项目根目录的 CONTRIBUTORS.txt 文件中，并维护联系信息。如果你是在你公司的保护伞下做贡献，请添加你公司的信息，不要也将自己列为额外的版权持有者。