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:

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:

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:

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:

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:

Click on Submit new issue to create your first issue.

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:

In a few moments, GitHub should complete forking the repository. You’ll find yourself in a familiar 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:

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:

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:

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:

This brings you to the pull request creation 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:

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:

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

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:

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:

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:

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!

The post Open-Source Collaboration Using Git and GitHub appeared first on Ray Wenderlich.