贡献

我们欢迎每个人为 Swift 做出贡献。贡献不仅仅意味着提交拉取请求——有许多不同的方式让你参与进来，包括在论坛上回答问题、报告或分类错误，以及参与 Swift 演进过程。

无论你想如何参与，我们都要求你首先通过阅读社区概述了解项目中任何参与者应该遵循的准则。如果你要贡献代码，你还应该知道如何从代码库构建和运行 Swift，这在源代码中有描述。

回答问题

支持社区最重要和最直接的方式之一是在论坛上回答问题。无论你是在帮助新手理解语言特性，还是与经验丰富的开发者一起排查边缘情况，你对 Swift 的知识和经验都可以极大地帮助他人。

报告错误

报告错误是任何人帮助改进 Swift 的好方法。开源 Swift 项目使用 GitHub Issues 来追踪错误。

如果一个错误只能在 Xcode 项目或 playground 中重现，或者如果这个错误与 Apple NDA 有关，请改为向 Apple 的错误报告系统提交报告。

在开启问题时，请包含以下内容：

对问题的简明描述。 如果问题是崩溃，请包含堆栈跟踪。否则，描述你期望看到的行为，以及你实际观察到的行为。
一个可重现的测试用例。 仔细检查你的测试用例是否能重现该问题。一个相对较小的样本（大约在 50 行代码以内）最好直接粘贴到描述中；较大的样本可以作为附件上传。考虑将样本减少到尽可能少的代码——更小的测试用例更容易推理，对贡献者来说也更有吸引力。
重现问题的环境描述。 包括 Swift 编译器的版本、部署目标（如果明确设置）和你的平台信息。

因为 Swift 正在非常活跃的开发中，我们收到了很多错误报告。在开启新问题之前，请花点时间浏览我们的现有问题以减少报告重复的机会。

在提交请求新语言功能的问题之前，请参阅Swift 演进过程部分。

分类错误

报告错误是改进软件的重要部分。几乎同样重要的是对这些错误进行分类，以确保它们是可重现的、简单的和独特的。

你可以做很多事情来帮助分类错误追踪系统中的错误。

重现错误。要使错误可操作，它需要是可重现的。如果你不能重现错误，试着找出原因。如果你需要更多信息，请联系提交者。
简化错误。一旦错误可以重现，将其减少到尽可能少的代码。对于一个只需几行 Swift 代码就能重现错误的样本进行推理比对一个更长的样本进行推理更容易。
消除重复错误。如果两个错误报告指向同一个底层问题，将较新的标记为较旧的重复。这样做可以让其他人更有效地工作。

网站和博客文章贡献

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

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

Swift 演进

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

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

好的第一个问题

好的第一个问题是针对新加入 Swift 项目的贡献者，甚至是新接触 Swift 编译器等子项目的模式和概念的贡献者的错误、想法和任务。好的第一个问题带有相应的标签，最容易通过访问 github.com/apple/<repository>/contribute 找到，例如 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) 2024 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) 2024 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 仓库起草拉取请求时切换到此模板，将 template=release.md 查询参数附加到当前 URL 并刷新。例如：
```
-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 项目对质量保持很高的标准。在提交到主要开发分支之前，任何更改必须满足的最低质量标准包括：

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

此外，提交者负责解决将来可能由更改导致的任何问题。这种责任意味着你可能需要更新你的更改以：

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

我们更喜欢在提交之前处理这些问题，但我们理解对于每次提交来说测试所有这些都是不可能的。我们的持续集成（CI）基础设施通常会发现这些问题。我们建议在接下来的一天里关注 CI 基础设施以查找回归。如果包含你的提交的一组提交导致失败，CI 基础设施会直接向你发送电子邮件。你应该检查这些消息，看看它们是否是你的错，如果是，就修复这个问题。

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

提交访问权限

提交访问权限授予给有提交高质量更改记录的贡献者。如果你想要提交访问权限，请向代码所有者列表发送电子邮件，附上你想使用的 GitHub 用户名和 5 个被接受而无需修改的非平凡拉取请求的列表。

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

你被授予对 Swift 所有部分的提交后批准权限。要获得批准，创建一个拉取请求。当拉取请求被批准后，你可以自己合并它。
你可以在不首先获得批准的情况下提交明显的更改。社区期望你运用良好的判断。例子包括还原明显损坏的补丁、更正代码注释和其他小的更改。
你被允许在没有批准的情况下向你已经贡献过或被分配责任的 Swift 部分提交更改。这样的提交不得破坏构建。这是一个”信任但验证”的政策，这种性质的提交在提交后会被审查。

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

添加外部库依赖

在某些情况下，Swift 项目（编译器、核心库等）使用提供特定平台功能的库可能是合适的。添加库依赖会影响 Swift 项目的可移植性，也可能涉及法律问题。

作为规则，所有新的库依赖必须得到项目负责人的明确批准。

LLVM 和 Swift

Swift 建立在 LLVM 编译器基础设施之上。Swift 使用 LLVM Core 进行代码生成和优化（以及其他事项），使用 Clang 实现与 C 和 Objective-C 的互操作性，使用 LLDB 进行调试和 REPL。

Apple 在 GitHub 上维护着 LLVM Core 源代码仓库的一个分支，名为 llvm-project。这个仓库跟踪上游 LLVM 的开发，并包含 Swift 的额外更改。上游 LLVM 仓库经常被合并到 Swift 特定的仓库中。尽可能将上游 LLVM 和 Apple 分支之间的差异最小化，仅限于 Swift 特别需要的更改。

LLVM 更改去向何处？

Swift 遵循在最上游可行的仓库中进行更改的政策。涉及 Apple 版本 LLVM 项目的 Swift 贡献应该直接进入上游 LLVM 仓库，除非它们是 Swift 特有的。例如，对 LLDB 中 Swift 类型的数据格式化程序的改进属于 Apple LLVM 项目仓库，而对 LLVM 优化器的错误修复——即使只在对 Swift 生成的 LLVM IR 操作时才观察到——属于上游 LLVM。

对上游 LLVM 仓库的提交会自动合并到相应的上游分支中的相应 Swift 仓库（llvm-project 中的 next）。

Swift 和 LLVM 开发者政策

对 Swift 的 LLVM 或 Clang 克隆的贡献受 LLVM 开发者政策管理，并应遵循适当的许可和编码标准。 LLVM 代码的问题使用 LLVM 错误数据库追踪。对于 LLDB，对带有 llvm.org 注释头的文件的更改必须进入 llvm.org 的上游 LLDB 并遵守 LLVM 开发者政策和 LLDB 编码约定。对 LLDB 的 Swift 特定部分（即那些带有 Swift.org 注释头的部分）的贡献使用 Swift 许可证，但仍然遵循 LLDB 编码约定。