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¶

The first 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 to the other through direct or indirect relationship (e.g. fork of the fork of the fork). Therefore, a pull request always originate from the fork repository page where "Create Pull Request" button will be available if the repository is related to another repository already published on mbed.org.

1 - Creating a pull request¶

The common case is when you publish a fork of someone else's repository that also contains your changes, enhancements, bug fixes, code refactoring etc. The mbed Developer site will recognize your repository as fork of the original repository and display it under repository details:

Notice the additional "Create Pull Request" button on top right. The button is visible only to you and other repository authors (if any).

Once you click it, you'll be taken to the "Create Pull Request" page where the URL fields for your and ancestor repository will be prefilled (see below).

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

It is important to add a suitable title and description that summarize the set of changes they should expect against their repository 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, which will add it as a new pull request in the "Pull Request" sub-page of their repository and also send them an email notification with the title and description you specified.

This article is unfinished. We are working on it!