Open source projects like Foundation are the results of thousands of gradual improvements. And while contributions can improve any open source product at GitHub, some changes are more helpful than others. Here's how to make a successful contribution, or pull request, to an open source product — and be part of something great.

What is a pull request?

Pull requests are changes you make to a copy — not the original — of a project at GitHub. Once made, you can submit your changes to be reviewed by the project's owners. If your changes are approved, the project's owners will "merge" them in to the project itself.

That approval project is crucial. When you make a change to a Git repository, pull requests tell people what you did and when. Far from a "big brother" situation, pull requests help everyone understand what happened at a given time to discover, "aha, yesterday's change affected what I'm trying to do now."

There are plenty of good guides about the technical aspects of making a pull request. Next we'll talk about what makes a good one.

Boosting your chances: What makes a useful PR

Good pull requests make sense weeks or months after they're submitted. When you submit a pull request to a project, it needs to be thorough and descriptive without going overboard. You need to describe your intent as well as your code changes. That's not always easy to do. Here are guidelines to follow:

• Include samples, if possible. A line of actual code is worth ten lines of description. Give or take.
• Describe how to reproduce the problem. Being able to break down the problem and test solutions is vital to getting something fixed without making the problem worse.
• Tell where the problem exists. In Foundation's case, that means naming the troubled component.
• Don't commit many files with only one description. Dozens of files with changes are difficult to decipher — and describe — in a single pull request.
• Don't revise an entire branch without documenting what you're up to. That way if the project's owner has to undo the change — a process called "rolling back" — they don't have to completely wipe out every change you made.

Examples of bad pull requests

Title: "Fix the 'push button on submit' problem"

Description: (none)

Problems: Vague title, no description. To quickly merge code into a project, we need to know why the change is necessary — for example, how we can reproduce the issue and how it negatively affects users.

---

Title: "@if should not be on same line as its curly braces"

Description: "http://sass-guidelin.es/ @if should not be on same line as its curly braces"

Problems: Description repeats the title, rendering it useless. The statement is a matter of opinion. While the author might have a good point, that point isn't backed up with facts or examples.

---

Title: "Unusual requests for the grid"

Description: "a while back I wrote a blog on a more advanced grid, and I thought it would be useful so here it is. If you are using the grid …"

Problems: Unasked for information and the wrong venue. GitHub is not Medium.

---

Title: "JS, firefox do not setup value in input"

Description: "OS X, Firefox. Browser will not put value to form field."

Problems: Not enough of the right kind of information. We need to know what component this regards, as well as what's happening and — once again — how to replicate the problem.

Examples of good pull requests

Title: "Abide rejects URLs with encoded characters"

Description: "Putting this URL into form results in an error from Abide: http://www.website.com/sample%20link"

Good: Concise description says what it needs to, and no more. As a bonus, it provides an example of the problem.

---

Title: "@else should be placed on the same line as the previous curly brace"

Description: "Adds clearing functionality, including preloading and auto-documentation. Also fixes problems with unit testing. This is great for testing in the component mixins."

Good: Explains why the change is important with definite examples.

---

Title: "Select list issue with ajax"

Description: "I have a drop-down select list that, after onMouseUp, is supposed to change an adjacent set of radio buttons via AJAX. However, onMouseUp it deletes all radio buttons from the DOM — except for the first. My code works OK until I add Foundation Forms, v5.4.1. See http://jsfiddle.net/sample/abc123/ for sample code."

Good: Provides expected results and the error, plus a link to the sample code. Also describes when the problem started — right after adding a particular component.

Each request may seem trivial, but they add up fast. Hundreds of minor, but well-written, changes conspire to make their project great as well.

---