Everyone is welcome to contribute to Swift. Contributing doesn’t just mean submitting pull requests—there are many different ways for you to get involved, including answering questions on the mailing lists, reporting or triaging bugs, and participating in the Swift evolution process.
No matter how you want to get involved, we ask that you first learn what’s expected of anyone who participates in the project by reading the Community Guidelines. If you’re contributing code, you should also know how to build and run Swift from the repository, as described in Source Code.
One of the most important and immediate ways you can support the community is to answer questions on the mailing lists. Whether you’re helping a newcomer understand a language feature or troubleshooting an edge case with a seasoned developer, your knowledge and experience of Swift can go a long way to help others.
Reporting bugs is a great way for anyone to help improve Swift. The open source Swift project uses Jira for tracking bugs. Our Jira instance is located at bugs.swift.org.
If a bug can be reproduced only within an Xcode project or a playground, or if the bug is associated with an Apple NDA, please file a report to Apple’s bug reporter instead.
When filing a new Swift bug, please include the following:
A concise description of the problem. If the issue is a crash, include a stack trace. Otherwise, describe the behavior you were expecting to see, along with the behavior you actually observed.
A reproducible test case. If the test case is small (for example, less than 20 lines of code) paste it directly into the issue’s description field. Otherwise, upload it as an attachment to the Jira issue.
A description of the environment that reproduces the problem. Include the Swift build number, as well as information about your target OS and platform.
Because Swift is under very active development, we receive a lot of bug reports. Before filing a new issue, take a moment to browse our existing issues to make sure you’re not filing a duplicate.
Before filing an issue requesting a new language feature, see Participating in the Swift Evolution Process.
Reporting bugs is an important part of improving software. Nearly as important is triaging those bugs to ensure that they are reproducible, small, and unique.
There are a number of things you can do to help triage bugs in the bug tracker.
Reproduce bugs. For a bug to be actionable, it needs to be reproducible. If you can’t reproduce the bug, try to figure out why. Get in touch with the submitter if you need more information.
Reduce bugs. Once a bug can be reproduced, reduce it to the smallest amount of code possible. Reasoning about a sample that reproduces a bug in just a few lines of Swift code is easier than reasoning about a longer sample.
Eliminate duplicate bugs. If two bug reports refer to the same underlying problem, mark the newer one as a duplicate of the older one. Doing so allows others to work more effectively.
The Swift project uses small, incremental changes as its preferred development model. Sometimes these changes are small bug fixes. Other times, these changes are small steps along the path to reaching larger stated goals. In contrast, long-term development branches can leave the community without a voice during development. Some additional problems with long-term branches include:
To address these problems, Swift uses an incremental development style. Small changes are preferred whenever possible. We require contributors to follow this practice when making large or otherwise invasive changes. Some tips follow:
Large or invasive changes usually have secondary changes that must be made before the large change (for example, API cleanup or addition). Commit these changes before the major change, independently of that work.
If possible, decompose the remaining interrelated work into unrelated sets of changes. Next, define the first increment and get consensus on the development goal of the change.
Make each change in the set either stand alone (for example, to fix a bug) or part of a planned series of changes that work toward the development goal. Explaining these relationships to the community can be helpful.
If you are interested in making a large change and feel unsure about its overall effect, please make sure to first discuss the change and reach a consensus through the developer mailing list. Then ask about the best way to go about making the change.
Although we don’t enforce a strict format for commit messages, we prefer that you follow the guidelines below, which are common among open source projects. Following these guidelines helps with the review process, searching commit logs, and email formatting. At a high level, the contents of the commit message should be convey the rationale of the change, without delving into much detail. For example, “bits were not set right” leaves the reviewer wondering about which bits and why they weren’t “right”. In contrast, “Correctly compute ‘is dependent type’ bits in ‘Type’” conveys almost all there is to the change.
Below are some guidelines about the format of the commit message itself:
For minor violations of these guidelines, the community normally favors reminding the contributor of this policy over reverting. Minor corrections and omissions can be handled by sending a reply to the commits mailing list.
When contributors submit a change to a Swift subproject, after that change is approved, other developers with commit access may commit it for the author. When doing so, it is important to retain correct attribution of the contribution. Generally speaking, Git handles attribution automatically.
We do not want the source code to be littered with random attributions like “this code written by J. Random Hacker”, which is noisy and distracting. Do not add contributor names to the source code or documentation.
In addition, don’t commit changes authored by others unless they have submitted the change to the project or you have been authorized to submit on their behalf—for example, you work together and your company authorized you to contribute the changes. The author should first either submit the change through a pull request to the relevant project, email the development list, or add a bug tracker item. If someone sends you a change privately, encourage them to submit it to the appropriate list first.
As mentioned in the Community Guidelines, the license and copyright protections for Swift.org code are called out at the top of every source code file. On the rare occasion you contribute a change that includes a new source file, ensure that the header is filled out appropriately.
For Swift source files the code header should look this:
Swift 台灣
// subfolder/Filename.swift - Very brief description
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2015 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See http://swift.org/LICENSE.txt for license information
// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
//
// -----------------------------------------------------------------------------
///
/// This file contains stuff that I am describing here in the header and will
/// be sure to keep up to date.
///
// -----------------------------------------------------------------------------
For C or C++ source or header files, the code header should look this:
//===-- subfolder/Filename.h - Very brief description -----------*- C++ -*-===//
//
// This source file is part of the Swift.org open source project
//
// Copyright (c) 2014 - 2015 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See http://swift.org/LICENSE.txt for license information
// See http://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.
///
//===----------------------------------------------------------------------===//
The divider lines should be exactly 80 characters wide to aid in adherence to the code style guidelines. The bottom section contains an optional description intended for generated documentation (these lines begin with /// rather than //). If there is no description, this area can be skipped.
The Swift project relies heavily on code review to improve software quality:
Code review can be an iterative process, which continues until the change is ready to be committed. After a change is sent out for review it needs an explicit approval before it’s submitted. Do not assume silent approval or request active objections to the patch by setting a deadline.
Sometimes code reviews will take longer than you would hope for, especially for larger features. Here are some accepted ways to speed up review times for your patches:
Note that anyone is welcome to review and give feedback on a change, but only people with commit access to the repository can approve it.
Developers are required to create test cases for any bugs fixed and any new features added, and to contribute them along with the changes.
swift/test directory.swift/test because this slows down testing for all developers. Please keep them short.People depend on Swift to create their production software. This means that a bug in Swift could cause bugs in thousands, even millions of developers’ products. Because of this, the Swift project maintains a high bar for quality. The minimum quality standards that any change must satisfy before being committed to the main development branch include:
swift/test and swift/validation-test test suites in the Swift compiler.Additionally, the committer is responsible for addressing any problems found in the future that the change may cause. This responsibility means that you may need update your change in order to:
We prefer that these issues be handled before submission, but we understand that it isn’t possible to test all of this for every submission. Our continuous integration (CI) infrastructure normally finds these problems. We recommend watching the CI infrastructure throughout the next day to look for regressions. The CI infrastructure will directly email you if a group of commits that included yours caused a failure. You are expected to check those messages to see whether they are your fault and, if so, fix the breakage.
Commits that clearly violate these quality standards may be reverted, in particular when the change blocks other developers from making progress. The developer is welcome to recommit the change after the problem has been fixed.
Commit access is granted to contributors with a track record of submitting high-quality changes. If you would like commit access, please send an email to the code owners list with the GitHub user name that you want to use.
Once you’ve been granted commit access, you will be able to commit to all of the GitHub repositories that host Swift.org projects. To verify that your commit access works, please make a test commit (for example, change a comment or add a blank line). The following policies apply to users with commit access:
You are granted commit-after-approval to all parts of Swift. To get approval, create a pull request. When the pull request is approved, you may merge it yourself.
You may commit an obvious change without first getting approval. The community expects you to use good judgment. Examples are reverting obviously broken patches, correcting code comments, and other minor changes.
You are allowed to commit changes without approval to the portions of Swift to which you have contributed or for which you have been assigned responsibility. Such commits must not break the build. This is a “trust but verify” policy, and commits of this nature are reviewed after being committed.
Multiple violations of these policies or a single egregious violation may cause commit access to be revoked. Even with commit access, your changes are still subject to code review. Of course, you are also encouraged to review other peoples’ changes.
Anyone with a good idea can help shape the future features and direction of the language. To reach the best possible solution to a problem, we discuss and iterate on ideas in a public forum. Once a proposal is refined and approved, it becomes a release goal, and is tracked as a feature of an upcoming version of Swift.
To support this process, the Swift Evolution repository collects the goals for the upcoming major and minor releases (as defined by the core team) as well as proposals for changes to Swift. The Swift evolution process document details how ideas are proposed, discussed, reviewed, and eventually accepted into upcoming releases.
See the Swift evolution review schedule for current and upcoming proposal reviews.
Swift is built on the LLVM Compiler Infrastructure. Swift uses the LLVM Core for code generation and optimization (among other things), Clang for interoperability with C and Objective-C, and LLDB for debugging and the REPL.
Swift maintains clones of the LLVM Core, Clang, and LLDB source repositories on GitHub as swift-llvm, swift-clang, and swift-lldb, respectively. These repositories track upstream LLVM development and contain additional changes for Swift. The upstream LLVM repositories are merged into the Swift-specific repositories frequently. Every attempt is made to minimize the differences between upstream LLVM and the Swift clones to only those changes specifically required for Swift.
Swift follows a policy of making a change in the most upstream repository that is feasible. Contributions to Swift that involve Swift’s versions of LLVM, Clang, or LLDB should go directly into the upstream LLVM repositories unless they are specific to Swift. For example, an improvement to LLDB’s data formatters for a Swift type belongs in the Swift LLDB repository, whereas a bug fix to an LLVM optimizer—even if it’s only been observed when operating on Swift-generated LLVM IR—belongs in upstream LLVM.
Commits to an upstream LLVM repository are automatically merged
into the appropriate upstream branches in the corresponding Swift
repository (upstream-with-swift in the swift-llvm and
swift-clang repositories, upstream in the
swift-lldb repository). The workflows for the Swift compiler and
LLDB differ slightly:
For the Swift compiler, the upstream-with-swift branches in
swift-llvm and swift-clang contain the
latest upstream LLVM sources along with the Swift-specific changes and
additions. The stable branch (against which most Swift development
occurs) is periodically rebranched from upstream-with-swift. In the
interim, important commits should be cherry-picked from llvm.org
into upstream-with-swift, and then into stable.
For LLDB, the upstream branch of swift-lldb contains
a mirror of the upstream LLDB
repository. The master
branch contains the Swift-specific code. The contents of upstream
are periodically merged into master at the same time that the Swift
compiler’s stable is rebranched. In the interim, important commits
should be cherry-picked from llvm.org into upstream, and then
into master.
Contributions to Swift’s LLVM or Clang clones are governed by the LLVM Developer Policy and should follow the appropriate licensing and coding standards. Issues with LLVM code are tracked using the LLVM bug database. For LLDB, changes to files with llvm.org comment headers must go to the upstream LLDB at llvm.org and abide by the LLVM Developer Policy and LLDB coding conventions. Contributions to the Swift-specific parts of LLDB (that is, those with a Swift.org comment header) use the Swift license but still follow the LLDB coding conventions.
Coming Soon!