Getting Started with Patches and Pull Requests

Introduction

If you would like to see some change in a Boost library, one approach is to submit a patch. There are two ways to accomplish that - submitting a traditional patch file, or submitting a pull request.

Traditional Patches

Traditional patches are submitted in the usual ways:

• Attach a diff to Boost developers list message explaining the patch. Easy to do, but least effective.
• Attach a diff to a patch ticket. Less likely to get lost in the shuffle than a mailing list attachment, but many developers prefer to get pull requests (see below).

Pull Requests

The preferred GitHub patch approach for open source projects is to fork the library involved, develop your patch, and then submit a pull request to the library maintainer. Here is what GitHub says about what they call the "Fork and Pull" approach:

The Fork & Pull Model lets anyone fork an existing repository and push changes to their personal fork without requiring access be granted to the source repository. The changes must then be pulled into the source repository by the project maintainer. This model reduces the amount of friction for new contributors and is popular with open source projects because it allows people to work independently without upfront coordination.

​Read the entire !GitHub article for more information on pull requests. Having a [https:/github.com !GitHub] account is a prerequisite, so open an account if you don't already have one.

Boost Library Pull Request Example

Here is how a pull request works for a Boost library:

First, using a web browser and your GitHub account, fork the Boost super-project and the Boost library you want to patch. The GitHub Bootcamp ​Fork a Repo instructions give all the details, but basically you just go to the boostorg repo and click the "Fork" button on the upper-right side of the super-project or library's repo page.

Then do the following from the command line:

1. Fork boostorg/boost
2. Clone *just* boostorg/boost, not all the sub-projects (as this will fail):
 - `git clone git@github.com:boostorg/boost.git modular-boost`
2.5 (Optional) Create a branch (I called mine 'updated')
3. Edit .gitmodules and change all the relative URLs to absolute, SSH
or HTTPS (whichever kind you or your company firewall likes).
 - I ran `:%s/\.\./https:\/\/github.com\/boostorg\/utility.git/g` in
vim to use https.
3. Fork the particular repos you want to apply patches to:
 - For this example, I forked 'range'.
4. Edit the 'range' url line in boost/.gitmodules to point to your fork:
 - I changed the https://github.com/boostorg/range.git to
git@github.com:ncrookston/range.git.
5. Commit your gitmodules change, push it to your fork:
 - `git commit -a -m "create local boostorg"; git push origin updated`
6. Now get all the submodules:
 - `git submodule update --init`.

You should see it fetch most libraries from boostorg, but those you've
edited will be registered with the URL you gave in step 4.

If you need to make a fresh clone it's straightforward:
If you created a new branch:
 - `git clone -b updated --recursive
git@github.com:ncrookston/boost.git modular_boost`
If you did not:
 - `git clone --recursive git@github.com:ncrookston/boost.git modular_boost`}}}

== Acknowledgements ==

Sohail Somani suggested the topic, Nathan Crookston worked out the steps given in the example.