A pull request lets you tell others about changes you've added to a fork of their (or ancestor) repository, effectively granting them permission to include and use your code in their code base. Once the pull request is created, the other party can review, accept or reject the set of changes, discuss further modifications and even add follow-up changes or merges.

Think of pull requests as for simplified fork and update workflow, where the changes contributed by non-repository developers are being moderated by the repository author(s).

Day to day usage¶

An important thing to know about pull requests is that they can only exist between related repositories. The term 'related repositories' means that either repository is ancestor or sibling to the other through direct or indirect relationship (e.g. fork of the fork of the fork). Pull requests usually originate from a fork repository to ancestor repository, though the functionality is flexible and allows sending pull requests from ancestor repository to a fork for cases where the original author wants to contribute later added code to a fork.

Creating a pull request¶

When you publish a fork of someone else's repository, the mbed Developer site will recognize it as fork of the original repository and display it under repository details:

An additional "Create Pull Request" button will be displayed on top that is only visible to you and other repository authors (if any).

Click it and you'll be taken to the "Create Pull Request" page, where the URL fields for your and ancestor repository will be prefilled like shown below:

You can change the remote repository URL if you want to send a pull request to another related repository. The form will validate the repository URL addresses as you type or paste, and it will warn if either of them is wrong, missing or unrelated. It will also check whether the forked repository (on left) has changes that aren't present in the remote repository (on right).

Add a suitable title and description that summarize the set of changes they should expect when reviewing it and specify any additional information they might find useful. It is also a good place to describe any licensing matter. As always, being polite goes a long way and they might even add you as author to their repository!

Click the "Send Pull Request" button when ready and the pull request will be added to the "Pull Requests" page of their repository, which will also send them an email notification with the title and description you specified.

All pull requests are created and recorded against the remote repository, the one receiving the modifications if the pull request is accepted.

Managing a pull request¶

When a pull request is sent to a repository to which you're author or co-author, you would receive an email notification with the pull request details and an http link to the pull request page. Alternatively, you can visit the repository page and click on the Pull Requests tab that will list all open pull requests:

The "Show all pull requests" will list all pull requests, including the closed ones (accepted and rejected).

On the pull request page you can have an open discussion about the changes, coding standards etc before accepting or rejecting, but once closed you won't be able to add more comments.

The "Close" button let's you quickly close the pull request for when you want to reject it without reviewing the changes.

The "Review" button takes us to the next topic...

Reviewing a pull request¶

Most online services that offer source code hosting and version control let you review and merge pull requests.
The mbed Online Tools steps one step further by letting you review, compile, test and add more changes if necessary before accepting a pull request by harnessing the power of the mbed Online Compiler.

To review pull request click the "Review" button on the pull request page and the mbed Online Compiler will open in new window. If you already have an instance of the mbed Compiler open, then open its tab.

[This article is unfinished. We are working on it!]