贡献

欢迎所有人为 Swift 做出贡献。贡献不仅仅意味着提交拉取请求，还有许多不同的方式让您参与其中，包括在论坛上回答问题、报告或分类错误以及参与 Swift 演化过程。

无论您想以何种方式参与，我们都要求您首先阅读社区概览，了解参与该项目的任何人都应遵守的期望。如果您要贡献代码，您还应该了解如何从存储库构建和运行 Swift，如源代码中所述。

回答问题

支持社区最重要和最直接的方式之一是在论坛上回答问题。无论您是帮助新手理解语言功能，还是与经验丰富的开发人员一起解决极端情况，您对 Swift 的知识和经验都可以为他人提供很大帮助。

报告错误

报告错误是任何人帮助改进 Swift 的绝佳方式。开源 Swift 项目使用 GitHub Issues 来跟踪错误。

如果错误只能在 Xcode 项目或 Playground 中重现，或者错误与 Apple NDA 相关，请向 Apple 的错误报告器提交报告。

打开 issue 时，请包含以下信息

由于 Swift 正在非常积极地开发中，我们收到了大量的错误报告。在打开新 issue 之前，请花一些时间浏览我们现有的 issue，以减少报告重复问题的可能性。

在提交 issue 请求新语言功能之前，请参阅Swift 演化过程部分。

分类错误

报告错误是改进软件的重要组成部分。几乎同样重要的是对这些错误进行分类，以确保它们是可重现的、小的和唯一的。

您可以通过多种方式来帮助分类错误跟踪器中的错误。

网站和博客文章贡献

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

在 网站治理流程中了解有关贡献本网站的更多信息，并了解如何提交博客文章贡献。

Swift 演化

塑造 Swift 的未来是社区共同努力的结果，任何人都可以通过 Swift 论坛的演化部分参与其中。Swift 演化过程涵盖了 Swift 语言和 Swift 标准库公共接口的所有更改，包括新的语言功能和 API、现有语言功能或 API 的更改、现有功能的删除等等。

请参阅Swift 演化审查计划，了解当前和即将进行的提案审查。

好的首个 Issue

好的首个 issue 是指旨在让 Swift 项目的新手贡献者，甚至是不熟悉 Swift 编译器等子项目背后的模式和概念的新手贡献者也能轻松上手的错误、想法和任务。好的首个 issue 会被标记上相应的标签，最容易通过访问 github.com/apple/<repository>/contribute 找到，例如主 Swift 存储库的 github.com/apple/swiftlang/contribute。它们预计是低优先级且范围适中的，不需要过多的重构、研究或调试——相反，它们应该鼓励新手涉足 Swift 的某些部分，更多地了解它，并做出真正的贡献。

任何具有提交权限并且对特定领域有见解的人都欢迎并鼓励找出或想出好的首个 issue。

贡献代码

开始使用

强烈建议您在自己的项目中熟悉 Swift 的使用，然后再直接为语言本身做出贡献。我们整理了方便的开始使用指南，其中包含分步说明，可帮助您启动并运行。

增量开发

Swift 项目使用小型的、增量的更改作为其首选的开发模型。有时这些更改是小的错误修复。有时，这些更改是朝着实现更大既定目标的小步骤。相比之下，长期开发分支可能会使社区在开发过程中失去发言权。长期分支的一些其他问题包括

为了解决这些问题，Swift 使用增量开发风格。尽可能首选小的更改。我们要求贡献者在进行大的或其他侵入性更改时遵循此实践。以下是一些提示

如果您有兴趣进行大的更改并且不确定其总体效果，请务必首先通过开发者论坛讨论更改并达成共识。然后询问进行更改的最佳方法。

提交消息

虽然我们没有强制执行严格的提交消息格式，但我们建议您遵循以下准则，这些准则在开源项目中很常见。遵循这些准则有助于审查过程、搜索提交日志和电子邮件格式。从高层次上讲，提交消息的内容应该传达更改的基本原理，而无需深入了解太多细节。例如，“位设置不正确”会让审阅者想知道哪些位以及为什么它们“不正确”。相比之下，“正确计算 ‘Type’ 中的 ‘is dependent type’ 位”几乎传达了更改的所有内容。

以下是关于提交消息本身格式的一些准则

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

变更归属

当贡献者向 Swift 子项目提交更改后，在该更改获得批准后，其他具有提交权限的开发人员可以为作者提交更改。这样做时，保留贡献的正确归属非常重要。一般来说，Git 会自动处理归属。

我们不希望源代码中充斥着像“此代码由 J. Random Hacker 编写”这样的随机归属，这既嘈杂又分散注意力。请勿将贡献者姓名添加到源代码或文档中。

此外，除非其他人已将更改提交到项目，或者您已被授权代表他们提交更改（例如，您一起工作并且您的公司授权您贡献更改），否则请勿提交其他人创作的更改。作者应首先通过拉取请求将更改提交到相关项目、通过电子邮件发送到开发列表或添加错误跟踪器项。如果有人私下向您发送更改，请鼓励他们首先将其提交到相应的列表。

代码模板

正如 社区概览 中提到的， 代码的许可和版权保护在每个源代码文件的顶部标明。极少数情况下，您贡献的更改包含新的源文件，请确保正确填写文件头。

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

//===----------------------------------------------------------------------===//
//
// This source file is part of the  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://swiftlang.cn/LICENSE.txt for license information
// See https://swiftlang.cn/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  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://swiftlang.cn/LICENSE.txt for license information
// See https://swiftlang.cn/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 批准，则无法合并。为了使更改被考虑包含在发布分支中，拉取请求必须具有

这里是一个示例。

代码审查

Swift 项目在很大程度上依赖于代码审查来提高软件质量

代码审查可能是一个迭代过程，持续到更改准备好提交为止。更改发送以供审查后，需要明确的批准才能提交。不要假设沉默即批准，也不要通过设定截止日期来要求主动反对补丁。

有时，代码审查会比您期望的要花费更长的时间，特别是对于较大的功能。以下是一些加速补丁审查时间的公认方法

请注意，欢迎任何人审查更改并提供反馈，但只有拥有仓库提交权限的人员才能批准更改。

测试

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

质量

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

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

此外，提交者有责任解决未来发现的任何由更改可能引起的问题。这种责任意味着您可能需要更新您的更改，以便

我们希望这些问题在提交之前得到处理，但我们理解不可能为每次提交都测试所有这些内容。我们的持续集成 (CI) 基础设施通常会发现这些问题。我们建议在接下来的一天中关注 CI 基础设施，以查找回归。如果包含您的提交的一组提交导致失败，CI 基础设施将直接通过电子邮件通知您。您需要检查这些消息以查看它们是否是您的错误，如果是，则修复损坏。

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

贡献者阶梯

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

当您通过在 GitHub 上为 Swift 做出贡献而攀登贡献者阶梯时，您将获得新的权限，同时也获得您需要履行的信任和责任。如果贡献者违反了这种信任和这些责任，核心团队可能会向他们发出通知，并在多次违规后撤销其级别。我们相信一个健康的社区，并希望永远不需要采取这种行动。

成员

成员是对 Swift 做出多次建设性贡献的人。此角色在整个组织中通用，成为成员后，您可以在 GitHub 上 swiftlang 组织中的所有仓库上触发 CI。

提交访问权限

提交访问权限授予给有提交高质量更改记录的贡献者。如果您想要提交访问权限，请发送电子邮件至 代码所有者列表，其中包含您要使用的 GitHub 用户名以及 5 个非平凡拉取请求的列表，这些拉取请求在未经修改的情况下被接受。

获得提交访问权限后，您将能够提交到托管 项目的所有 GitHub 仓库。要验证您的提交访问权限是否有效，请进行测试提交（例如，更改注释或添加空行）。以下策略适用于具有提交访问权限的用户

多次违反这些策略或一次性质恶劣的违规行为可能会导致提交访问权限被撤销。即使拥有提交访问权限，您的更改仍然需要接受代码审查。当然，也鼓励您审查他人的更改。

代码所有者

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

任何人都可以审查一段代码，我们欢迎所有感兴趣的人进行代码审查。代码审查程序不受中央全球策略的约束。相反，该过程由每个代码所有者定义。

任何活跃且表现出价值的社区成员都可以通过在论坛上发帖来申请成为代码所有者，或者由另一位成员提名。如果其他贡献者同意，项目负责人将进行任命并将新所有者的姓名添加到代码所有者文件中。该职位完全是自愿的，可以随时辞职。

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

对于 Swift 的成功而言，可能没有什么比强大而积极参与的代码所有者更重要了。我们都应该对他们表示尊重、感激，并在力所能及的范围内提供帮助。

每位贡献者负责将自己的名字添加到项目根目录下的 CONTRIBUTORS.txt 文件，并维护联系信息。如果您以公司名义贡献，请添加贵公司的信息，请勿将您自己列为额外的版权所有者。