Creating pull requests on GitHub

Whereas many project communities accept code only through mailing lists or complex websites, Salt has opted to stick with pull requests for accepting code contributions. A list of active pull requests can be found at:

https://github.com/saltstack/salt/pulls

The complete details of using Git are way beyond the scope of this book, but it is worth going over the steps to clone the Salt repository and put in a new pull request.

First, you will need your own fork of Salt on GitHub. If you don't have one yet, then use the Fork button at Salt's own GitHub page:

https://github.com/saltstack/salt

Assuming that your GitHub username is mygithubuser, your new fork will appear at:

https://github.com/mygithubuser/salt

Once you have a fork set up, you'll need to clone a copy to your computer. The following steps assume that you work in a command-line environment, such as Linux:

1. If you have an SSH key set up, you can clone using SSH:

   $ git clone [email protected]:mygithubuser/salt.git
   

   Otherwise, you'll need to clone over HTTPS:

   $ git clone https://github.com/mygithubuser/salt.git
   

2. You will also need to add the original SaltStack repository to your local clone, to be able to create pull requests:

   $ git remote add upstream https://github.com/saltstack/salt.git
   

3. The default Git branch is develop. If you're adding a new feature to Salt, the work should be performed on a branch based on develop. To create a new branch called newfeature and switch to it, use:

   $ git checkout -b newfeature
   

4. When you are ready to put in a pull request, it is best to rebase your branch to make sure it doesn't conflict with any other pull requests that have been merged since your last update:

   $ git checkout develop
   $ git fetch upstream
   $ git pull upstream develop
   $ git checkout newfeature
   $ git rebase develop
   

   Note

   For more information on using rebase, check out:

   https://help.github.com/articles/using-git-rebase/

5. Once you have rebased, go ahead and push your branch up to GitHub:

   $ git push origin newfeature
   

6. When you visit your fork on GitHub again, you will see a link that says New Pull Request. From there, you can look at the diff readout between your branch and the current version of the develop branch on GitHub, and create your pull request when you're satisfied with it.

As with issue submission, pull requests now also have a template to use as a guide to provide useful information about describing the changes that your pull request includes.

Using other branches

If you're submitting bug fixes, then it may be more appropriate to submit them against a branch that matches a specific version of Salt. If you know which version of Salt the bug was first found in, then use that branch. The exception would be if the branch in question is so old that it is no longer being maintained. If that is the case, then choose the oldest branch that is being maintained. For instance, if the oldest maintained version is 2015.8.x, then check out the 2015.8 branch:

$ git checkout 2015.8