Contributing to Swift for the First Time

As Swift continues to evolve and engage a broader set of developers, many are excited by the possibility of contributing to Swift development. However, even for experienced engineers contributing to such a well-known and public project can be daunting.

Fortunately, there are many ways to contribute to Swift and related projects, accessible for all ability levels. This post walks through the journey, from start of finish, of contributing to Swift from the first time:

  1. Everyone can contribute to Swift
  2. The Swift contribution process
  3. Building Swift projects on your local machine
  4. Picking a contribution right for you
  5. Testing your contribution
  6. Submitting a Pull Request

The contents of this post formed a talk I presented at try! Swift and Altconf 2019 (video). My first contribution merged into Swift was IndexSet.union performance improvement.

Everyone can contribute to Swift

The Swift ecosystem welcomes developers of all backgrounds to contribute to a wide array of projects. Swift experience is not required! Many projects have opportunities to contribute in C++, C, Python, and other languages.

All official Swift projects are hosted on Apple’s Github. Some of the most active projects are:

Swift, "The Swift Programming Language."
Primary Languages: C++, Swift

Swift Package Manager, "The Package Manager for the Swift Programming Language."
Primary Language: Swift

Swift CoreLibs Foundation, "The Foundation Project, providing core utilities, internationalization, and OS independence."
Primary Languages: Swift, C, C++

SwiftNIO, "Event-driven network application framework for high performance protocol servers & clients, non-blocking."
Primary Language: Swift

LLVM Project, "The LLVM Project is a collection of modular and reusable compiler and toolchain technologies. This fork is used to manage Apple’s stable releases of Clang as well as support the Swift project."
Primary Languages: C++, LLVM, C, Assembly

The Swift contribution process

There are three ways to contribute to the Swift ecosystem:

  1. Answer questions on the Swift forums at forums.swift.org. The Swift forums contain a number of threads focused on different aspects of the Swift ecosystem:
    a. Evolution: "Topics related to the Swift Evolution Process."

    b. Development: "Topics related to development and implementation of Swift"

    c. Using Swift: "This area is intended for users to get help with or ask questions about Swift or its related tools. Beginner questions welcome!"

  2. Reporting and Triaging Bugs. Swift projects use JIRA to manage development tasks at bugs.swift.org.
    a. Report new bugs. If you find a bug in a Swift project, check to see if the bug has been previously reported. Reporting bugs helps issues get fixed faster, improving Swift for everyone.

    b. Triage bugs. Reporting a bug is only the first step. Bugs need to be reproducible with concise example code, and de-duplicated. Helping reproduce, shorten code examples, and de-duplicate bug tickets is an important part of the Swift development process.

Note from the Swift website: "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."

  1. Contributing code. Swift is a living and growing ecosystem, meaning there is always plenty that needs to be done. Contributing code to a Swift ecosystem project occurs in stages:
    a. Incremental development. Swift projects prefer smaller, incremental changes to large, invasive changes. If you plan to tackle a larger scope, decompose the related work into a set of smaller commits that can be independently reviewed.

    b. Code review. All major changes by all developers are code reviewed. The entire process occurs on Github. If you are interested in seeing what code review looks like, look for closed pull requests with multiple comments.

    c. Testing. Each Swift project has one or more test sets that need to be passed for the change to be committed. For some projects, tests across multiple platforms need to be passed. In most cases, you can run tests locally relevant to your change and let Github run the full test suite in the cloud.

    d. Acceptance. After code review and tests are passed, the change is merged into the project.

Building Swift projects on your local machine

A great way to get started is to pick the Swift project that interests you most and get the test cases running on your machine. First, Fork the codebase so you have a copy in your Github account that you will be able to branch from.

Next, clone the repository on your local machine. Consider using --depth 1 to clone the current state of the repository without the entire commit history.

// Example command to clone my Swift fork
git clone git@github.com:RobertPieta/swift.git --depth 1

Tip: Most Swift projects target the latest or very recent versions of Swift and the Swift compiler. When contributing to Swift use the latest release version of Xcode to avoid potentially hard to debug Swift compiler errors.

Picking a contribution right for you

I recommend picking a topic your are passionate about and finding a contribution inside of that topic. The Swift ecosystem emcompasses all the parts of the development process, from formal Swift evolution proposals to rigorous testing.

Potential topics for you to consider are:

  1. Performance
  2. Bug Fixes
  3. Documenation and Compiler Help Tips
  4. Test Coverage
  5. Cross-Plaform Support
  6. Developer Tools
  7. New Features

Testing your contribution

Testing is an important part of contributing to the Swift ecosystems. Developers all around the world rely on Swift to ship incredible apps. After implementing your contribution, follow these steps to get the contribution ready for submission:

  1. Run unit tests locally. Passing test cases on your local machine is the first step in preparing a contribution for submission.
  2. Add additional tests if needed. Sometimes your contribution adds functionality or another code path that should be tested.
  3. Add comments. Comments will help the reviewer understand your thought process and help other developers in the Swift ecosystem understand your contribution.
  4. Ask friends for feedback. Swift reviewers are responsible for a large number of Pull Requests, and may take some time before they can review your contribution. Friends may be able to get you feedback faster.

I am happy to take a look at any Swift contributions! Shoot me a tweet @RobertPieta

I went through these exact steps to prepare my first contribution to Swift, a performance improvement to IndexSet.union, for submission. Here is the resulting contribution:

public func union(_ other: IndexSet) -> IndexSet {
    var result: IndexSet
    var dense: IndexSet

    // Prepare to make a copy of the more sparse IndexSet to prefer copy over repeated inserts
    if self.rangeView.count > other.rangeView.count {
        result = self
        dense = other
    } else {
        result = other
        dense = self
    }

    // Insert each range from the less sparse IndexSet
    dense.rangeView.forEach {
        result.insert(integersIn: $0)
    }

    return result
}

Submitting a Pull Request

Once your change passes tests locally, has comments, and you are confident in the change you are ready to submit a Pull Request. Here are some things I found useful when preparing and submitting a Pull Request:

  1. Occasionally recently merged changes may impact the change you made or the tests you need to pass. Before creating a PR make sure to rebase your branch to master using git rebase master so you have the latest copy.
  2. Rename your local branch containing your change to something clear and concise using git branch -m old_name new_name. In my first contribution I called my branch IndexSet.union_performance.
  3. Look at other Pull Requests with similar types of changes to get a sense of what kind of Title and Description you need. I looked at similar performance contributions and submittted a Pull Request with the following title and description:

IndexSet.union performance improvement
Improves performance of IndexSet.union by replacing a loop with a struct copy of the more sparse set.

  1. Courtesy pings are ok if the assigned reviewer for you contribution hasn’t responded in over a week. Reviewers are people too working all around the world!
  2. For Pull Requests to the Swift project, check out the very detailed guide How to Submit Your First Pull Request

Becoming A Swift Contributor

That’s it! Check out a Swift repository, visit bugs.swift.org/issues, or jump into the forums to start your journey to becoming a Swift Contributor.