Open-Source Collaboration Using Git and GitHub

Kelvin Lau
Note: This tutorial assumes the following:

  • You already have a GitHub account. If you don’t, sign up for a free one here.
  • Git is installed on your system. You can check this by opening up Terminal and typing which git. If there’s a result — typically /usr/bin/git — then you’re good to go. If not, you can install Xcode or download an installer from the Git website here.

Open-Source Collaboration Using Git and GitHub

You’ve come across a project on GitHub you want to contribute to. Great! That seems easy enough. But working on a global, open-source project can be quite intimidating for first-timers.

In this tutorial, you’ll learn the ins and outs of contributing to open-source by moving through the entire workflow of open-source contributions, from retrieving the code, to creating issues, to pushing your new contributions. And you’ll get a good laugh along the way as you dive into the tutorial’s sample project!

Getting Started

Open-source development is a huge part of the software development industry. Many tools and libraries you use everyday have been shaped by millions of humans all around the globe. Dependency managers such as CocoaPods and Carthage that iOS developers use daily are driven by public contributions. Even the Swift language itself is open-source.

There are many reasons to contribute to open-source projects:

  • It’s a great way to build a highly accessible portfolio. Your GitHub profile can be a treasure trove of your technical expertise for inquiring minds.
  • Open-source contributions rely on collaboration between fellow developers. Your participation and contributions to project discussions are an excellent indication of your abilities as a team player.
  • Current and future employers, along with your peers in the industry, will take note of your work in the community.
  • It’s a great way to learn and expand your development skills!

Contributing to open-source starts by choosing the project you want to contribute to. One way to find a project that is relevant to your interests is to check out the topics section in GitHub. Here’s the Swift topic list:

List of Swift Category Projects on Github

Checking out the trending category is a good way to find popular projects as well.

If you know exactly which repo you want to contribute to, you can also visit the project page directly. Last year, Ray Wenderlich unloaded many programming dad jokes at RWDevCon, leaving the audience gasping for air.

In an effort to bring more humor to the programming industry, you’ll be contributing your very own programming dad jokes to our first open-source joke repository.

Navigate to the URL for the repository for this tutorial — https://github.com/raywenderlich/DadJokes and you should see the DadJokes project on GitHub.

You should see something like this:

RayWenderlich Dad Jokes Repository on Github

Keep this page handy, you’ll be visiting it often.

A Bit of Terminology

Before you begin piling on the puns, you’ll need to know some common terminology behind open-source-projects.

Repo

Short for repository, a repo is a project on GitHub. DadJokes can therefore be classified as a repo. You’ll use and hear this word fairly often in your forays into open-source.

Maintainers

“Maintainers” refers to the users who have permission to make changes to the repo. The owner of the repo has power to grant different level of privileges to certain users. The ability to set these access levels is important to prevent malicious users from altering the code – or in this case, blunting the puns.

README

The README file usually refers to the Markdown file that summarizes what the project is about.

Raising an issue

A good first step in the open-source process is to look at an issue. An issue is a way to create a discussion in the community, whether it’s to bring up a question, provide feedback, or contacting the maintainers.

Navigate to the DadJokes repo and click on the Issues tab:

Github Issues tab image

This tab contains a list of issues raised by community members. You’ll begin your adventure by creating an issue.

Click the green New Issue button, and you should see the following:

Github New Issue Page

If contributing guidelines are available for a repo, you’ll see a warning dialog. Since you’re a good citizen, click on the highlighted contributing text and check out the rules.

After being humored by the contributing guidelines, head back to the issue creation page. The first order of business is to create a title. Write Joke as your title.

Next is the body of the issue. You should see some pre-filled text. If the maintainer added an ISSUE_TEMPLATE.md file to their repository, GitHub will render the contents of the file as a template for every new issue.

For this particular issue, write the following into the issue body:

Issue created in response to #1

### Question
What did the Swift String hash function say to the others?

### Answer
I Sip Hash Are You?

All GitHub issues are paired with a number. This number can be referenced within the repository, allowing you to “deep link” an issue from various discussions. In this particular issue, you’ve referenced issue #1 as part the body. Click the Preview tab to check out the issue:

Preview of the issue to submit on Github

Click on Submit new issue to create your first issue.

Note: I’m terrible at making dad jokes. SipHash is the hashing algorithm for Swift strings. You can check out the source code for that here.

Downloading a Repo

After writing an issue, you’ll probably wait for feedback to decide how to proceed. While you wait for that, you’ll explore the project in depth. The first step is to actually get the project code onto your machine.

Forking

Before downloading someone else’s repo, you’ll need to create a fork, which is a personal copy of someone else’s project. Forks act as a bridge between the original repository and your personal copy.

Create a fork by clicking on the Fork button located at the top-right corner of the repo:

Github showing the Fork button for a repository

Note: If you belong to multiple organizations, you’ll be prompted to choose where the fork should reside in. Choose your personal account.

In a few moments, GitHub should complete forking the repository. You’ll find yourself in a familiar page:

Forked Github repository page

This is your personal replica of the original repo. You’re free to make any changes with this copy, and it won’t affect the original one. Now that you have your fork, it’s time to clone it onto your computer.

Cloning

In your fork of the DadJokes repo, click on Clone or download, and you should be presented with a popover dialog:

Github clone / download popover dialog

Make sure you’re cloning with HTTPS, and copy the link. Next, open Terminal and execute the following:

cd ~/Desktop
git clone <your copied HTTPS url here>

This will clone the repository in your Desktop directory.

Exploring the Project

After cloning the repository, you should see a new folder named DadJokes on your desktop. Navigate into the project folder and open DadJokes.xcodeproj in Xcode. Build and run the app on an iPhone simulator, and you should see the following:

DadJokes application initial joke list

Depending on when you read this article, there may be a few new jokes added by other contributors. The more the merrier, I say!

Making Contributions

Bring up Terminal again. Execute the following commands in Terminal:

cd ~/Desktop/DadJokes
git checkout -b feature/my-new-joke

This creates a new branch for the new modifications you’ll be making to the source code. Next, open JokeStore.swift and find the following line:

private var storage: [Joke] = [
  // ...
]

storage is a hard-coded array of Joke structures. The table view controller from earlier lists all the jokes contained in this array. To contribute to this project, you’ll need to add a joke (or a few) in this array.

Add a new Joke at the front of storage:

private var storage: [Joke] = [
  // add new joke here (feel free to add your own)
  Joke(description: "You should be careful with functions that return a value...", 
    punchline: "In fact, I would just a void them."),

  // ... other jokes
]

Build and run. You should see the new joke at the top of the table view:

Dadjokes application displaying your new joke

Pushing to Your Remote

A remote refers to the location of the repository on GitHub. Now you’ve made some changes to your personal copy project, it’s time to push the changes to your remote. Type the following in Terminal:

git add .
git commit -m "Added new joke"
git push --set-upstream origin feature/my-new-joke

You may have to enter your GitHub login and password upon pushing. Once you’ve done that, your changes will have been pushed back up to GitHub. Your personal copy is now updated with the new joke, but the original repo won’t be able to see the changes. To make them visible, you’ll have to submit a pull request.

Pull Requests

A pull request is proposed change to a project in a GitHub repository. The community can view this pull request to discuss the change and any potential modifications.

Head back to the original DadJoke repository and click on New pull request:

Original DadJokes repository highlighting the New Pull Request button

This brings you to the pull request creation page:

Create Pull Request Github page

Your new joke is in your personal fork of the repo, so you’ll need to click on compare across forks. This brings up the following UI:

Github compare across forks UI

The left options represent the base fork and branch. Since you want to create a pull request for the original repository and the master branch, you’ll leave those two options alone. You need to modify the two options on the right side. Update them to match your own fork and your new branch. Here’s an example of what it would look like:

Modifying the forked repository option on Github

Modifying the faked repository branch with the changes on Github

With that, you’re presented with a similar UI to the issue creations page:

Pull Request creation page Github

This is the final step before publicly announcing your proposal to the community. The bottom section of the page shows a summary of the changes you’ve proposed for this pull request.

Change the title of the pull request to <your name>’s Joke (substituting your own name into the angle brackets), and add the following for the body:

This addresses issue #1. Adds a dad joke.

#1 creates a reference to the issue or pull request with that number. In this case, #1 refers to the issue asking for more jokes. When you create a PR, strive to be concise and reference related discussions. This gives more context to your PR and makes it easier for maintainers to review and give feedback.

Click on Create pull request to publish it to the public.

Reviewing a PR

GitHub has a great tool for streamlining the review process. This tool can be accessed by clicking on the Files changed tab of a particular pull request:

Viewing a pull requests files changed tab on Github

The “Files changed” tab lists all the changes being proposed by a particular pull request. Additions are highlighted as green, while removals are highlighted as red.

Hover over the green line where you added your joke. You should see a blue “+” button to the left of the line. Click on it:

Writing a comment for a specific change within your pull request Github

When doing reviews, you’ll be going through each change and giving comments if necessary. Write LOL, my sides :+1: in the text view and click Start a review. Comments created this way will be batched until you submit the review, so don’t be afraid to take a break for bigger PRs.

Since this one’s fairly small, you’ll have to be content with just that one comment. Click Finish your review and leave a summary of your findings:

Submit review screen Github

Normally you wouldn’t review your own contribution, but for the sake of this tutorial, you’ve done just that. Head over to the other PRs and apply the same procedure to give your opinions!

Where to Go From Here?

I hope you’ve enjoyed this tutorial on open-source contributions. There are lots of projects out there, and you’re now equipped to contribute to them. There are related tutorials of interest if you want to know more:

  • The Swift Algorithm Club is one of the most popular Swift repositories on GitHub. Check out the introductory article to learn more about contributing to it.
  • The beginning git video course is a great way to learn more about git version control. If you want to be an open-source contributor, having a thorough knowledge of git is highly beneficial.

If you have any questions or comments, please join the discussion below!

Team

Each tutorial at www.raywenderlich.com is created by a team of dedicated developers so that it meets our high quality standards. The team members who worked on this tutorial are:

Kelvin Lau

Kelvin is a Swift Developer. He currently maintains the Swift Algorithm Club. In his free time, he dabbles in web development and server side Swift.

Outside of programming work, he's an aspiring entrepreneur. You can find him on his twitter at @KelvinlauKL

Other Items of Interest

Save time.
Learn more with our video courses.

raywenderlich.com Weekly

Sign up to receive the latest tutorials from raywenderlich.com each week, and receive a free epic-length tutorial as a bonus!

Advertise with Us!

PragmaConf 2016 Come check out Alt U

Our Books

Our Team

Video Team

... 27 total!

iOS Team

... 74 total!

Android Team

... 33 total!

Unity Team

... 15 total!

Articles Team

... 12 total!

Resident Authors Team

... 29 total!

Podcast Team

... 7 total!

Recruitment Team

... 9 total!