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:
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
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
The default Git branch is
develop
. If you're adding a new feature to Salt, the work should be performed on a branch based ondevelop
. To create a new branch callednewfeature
and switch to it, use:$ git checkout -b newfeature
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
Once you have rebased, go ahead and push your branch up to GitHub:
$ git push origin newfeature
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.
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