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 [[/handbook/Collaboration/Getting-started#forking-a-repository|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).

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!

When you've formatted your pull request, click the "Send Pull Request" button, will add it to the "Pull Request" sub-page of their repository and also send them an email notification with your title and description.

This article is unfinished. We are working on it!