A simple guide to creating a GitHub Pull Request

The biggest challenge as a Free Open Source Software project like Perfect is how to enable community involvement while maintaining quality and a cohesive direction. As members of the project’s “core” team, we are often so close to the code we don’t see edge cases or take into account situations we have yet to encounter — which is where people who use the libraries and encounter issues, bugs, or optimization opportunities are vital to a project’s maturity.

Fortunately git, and in our specific case, GitHub, make community contributions easy, using a process called the “Pull Request”.

“I would love to do a Pull Request for this, but I have no idea how to do it”

In our daily discussions on the open community Slack group, when being informed of documentation or code change needs the comment has been made several times that “I would love to do a pull request for this, but I have no idea how to do it”.

Well, if you’ve said or ever thought that and have hesitated to contribute to a FOSS project, read on!

What is a “Pull Request”

The terminology “Pull Request” is a little strange, and doesn’t equate well to anything outside the git community, aside from maybe the concept of a “patch”.

In reality, a pull request (a.k.a. PR) is a way for you to submit changes to code while promoting open dialogue and review.

A simple explanation of a PR is:

• you make modifications to your own copy of a git repository
• once you are satisfied, you trigger a request to merge your changes into the original repository, with an explanation of what you did and why
• a project administrator then reviews your changes and accepts them or initiates discussion on the changes.

A pull request in action

To demonstrate, step-by-step, how you as the reader can do a PR yourself, I’m going to describe the process of doing a PR to the Perfect Documentation repository.

The whole documentation set for the Perfect project is open source, and we periodically update the HTML version on the main site — generated from the GitHub repo’s Markdown files. This means that if you spot a typo or an improvement that can be made, you have the power to help out!

So I noticed today that the version mentioned in the CouchDB driver docs was incorrect: it referenced a majorVersion of 0, when it should be 1.

Heading over to the GitHub repo page that is it’s source, https://github.com/PerfectlySoft/PerfectDocs/blob/master/guide/CouchDB.md, I can see that it’s out of date there too, so it needs to change.

First step, “fork” the repository.

Whoah, more git terminology: A “fork” is an intentionally new version of the repository made at a specific point in time. Imagine if you were walking down a forest trail, and suddenly the path divides into two — this is a “fork”. One path might continue to the intended destination, and the other may take you in an entirely different direction… and sometimes will merge back into the original trail.

A “fork” is an intentionally new version of the repository made at a specific point in time.

To create a fork of the Perfect docs repository, use the “Fork” button near the top right of the GitHub page.

You are then presented with a dialog asking you where you’d like to place your new fork. Choose a location: your list may be shorter, or longer than mine…

Now we have our own fork, we can edit files.

Editing and committing your changes

For small changes like we’re going to make, the GitHub user interface makes it easy. For more extensive changes (especially involving code) I suggest cloning your new repo to your local environment and using an IDE like Xcode to edit and test the code before committing.

Seeing as this demonstration is changing one small part of documentation I’m going to edit directly within the GitHub UI.

When on the page viewing the file in your own repo, you will see a pencil icon for entering the edit mode:

Clicking this will flip you into edit mode. Scroll to the place you want to make a change — in my case I want to update the “0” to be “1”.

When you’ve done with the change, scroll down to the “commit message” portion of the page, and enter a brief description of what you’ve changed:

Now, this change is still on your copy (fork) of the Docs repo, so the next step is to bring the paths back together.

Submitting your Pull Request

When looking at the “root” of your forked repository (the one that also shows the Readme), you will see a button labelled “New pull request”. Clicking this will take you to a page that is dedicated to showing you all the differences between your version, and the parent. It will also notify you if there are any merge conflicts that would prevent success.

Click on the big green button “Create Pull Request”, which then gives you the opportunity to summarize all the changes you have made in the PR.

Clicking “Create pull request” now will show you the publicly viewable PR entry in the parent repository. Note that there’s a “CLA Assistant” comment in orange, plus a message that “Some checks haven’t been completed yet”…

This “CLA” is the “Contributor Licensing Agreement”, and is in place to clean up assignment of any licensing issues. If you wish to read more about the CLA process, check out the Wikipedia article on CLA’s, and read Perfect’s CLA.

Clicking the button will take you to a page where you can agree to the terms, which is required for many FOSS projects to accept a PR. At the bottom is a “Sign in with GitHub to agree” button. Clicking this takes you back to the PR review page, and everything is now green!

What Happens after you submit a Pull Request?

Good question! In an ideal world one of us will quickly see and act on evaluating the PR. However due to the vagaries of schedules, email spam filters and general busyness of life we might miss the notification. The 100% best way to let us know is to pop on the Perfect Slack channel and let us know in #general (or #docs) by mentioning myself (@iamjono)or Kyle (@kylej).

We will then handle or delegate the review of the changes.

We strongly believe in collaborative coding, diversity of ideas, and celebrating the contributions of the developer community as a whole. Even if you’re not part of the Perfect Server Side Swift community and would like to contribute to it, or any other FOSS project, please don’t hesitate. Software only gets better with more eyes and hands involved.

If you have any questions on the PR process, the Perfect project, or Server Side Swift in general — you can catch me on the Perfect Slack channel as @iamjono and on Twitter as @iamjono.