Contributing¶

Sending a GitHub pull request¶

Sending pull requests on GitHub is the preferred method for receiving contributions. The workflow advice below mirrors GitHub's own guide and is well worth reading.

1. Fork the saltstack/salt repository on GitHub.

2. Make a local clone of your fork.

3. Create a new branch in your clone.

   A branch should have one purpose. For example, "Fix bug X," or "Add feature Y." Multiple pull requests should be opened for unrelated changes.

   Choose a name for your branch that describes its purpose.

   git checkout -b fixed-broken-thing
   

4. Make edits and changes locally.

5. Commit changes to this new branch.

   Edit the necessary files in your Salt clone and remember to add them to your commit. Write a descriptive commit message.

   git add path/to/file1
   git add path/to/file2
   git commit -m "Fixed X in file1 and file2"
   

   If you get stuck there are many introductory Git resources on help.github.com.

6. Push your locally-committed changes to your GitHub fork.

   git push --set-upstream origin fixed-broken-thing
   

7. Go to your fork on the GitHub website & find your branch.

   GitHub automatically displays a button with the text "Compare & pull request" for recently pushed branches.

   Otherwise click on the "Branches" tab at the top of your fork. A button with the text "New pull request" will be beside each branch.

8. Open a new pull request.

   1. Click one of the pull request buttons from the previous step. GitHub will present a form and show a comparison of the changes in your pull request.
   2. Write a descriptive comment, include links to any project issues related to the pull request.
   3. Click "Create pull request".

9. The Salt repo managers will be notified of your pull request.

   If a reviewer asks for changes:

   1. Make the changes in your local clone on the same local branch.
   2. Push the branch to GitHub using the same command as before.
   3. The new commits will be reflected in the pull request automatically.
   4. Feel free to add a comment to the discussion.

Which Salt branch?¶

GitHub will open pull requests against Salt's main branch named develop by default. Most contributors can keep the default options. This section is for advanced contributors.

Each pull request should address a single concern, as mentioned in the section above. For example, "Fix bug X," or "Add feature Y." And a pull request should be opened against the branch that corresponds to that concern.

Keeping Salt Forks in Sync¶

Salt is advancing quickly. It is therefore critical to pull upstream changes from upstream into your fork on a regular basis. Nothing is worse than putting hard work into a pull request only to see bunches of merge conflicts because it has diverged too far from upstream.

The following assumes origin is the name of your fork and upstream is the name of the main saltstack/salt repository.

1. View existing remotes.

   git remote -v
   

2. Add the upstream remote.

   # For ssh github
   git remote add upstream [email protected]:saltstack/salt.git
   
   # For https github
   git remote add upstream https://github.com/saltstack/salt.git
   

3. Pull upstream changes into your clone.

   git fetch upstream
   

4. Update your copy of the develop branch.

   git checkout develop
   git merge --ff-only upstream/develop
   

   If Git complains that a fast-forward merge is not possible, you have local commits.

   • Run git pull --rebase origin develop to rebase your changes on top of the upstream changes.
   • Or, run git branch <branch-name> to create a new branch with your commits. You will then need to reset your develop branch before updating it with the changes from upstream.

   If Git complains that local files will be overwritten, you have changes to files in your working directory. Run git status to see the files in question.

5. Update your fork.

   git push origin develop
   

6. Repeat the previous two steps for any other branches you work with, such as the current release branch.

Posting patches to the mailing list¶

Patches will also be accepted by email. Format patches using git format-patch and send them to the salt-users mailing list. The contributor will then get credit for the patch, and the Salt community will have an archive of the patch and a place for discussion.

Backporting Pull Requests¶

If a bug is fixed on develop and the bug is also present on a currently-supported release branch it will need to be back-ported to all applicable branches.

It is often easiest to fix a bug on the oldest supported release branch and then merge that branch forward into develop (as described earlier in this document). When that is not possible the fix must be back-ported, or copied, into any other affected branches.

These steps assume a pull request #1234 has been merged into develop. And upstream is the name of the remote pointing to the main Salt repo.

1. Identify the oldest supported release branch that is affected by the bug.

2. Create a new branch for the back-port by reusing the same branch from the original pull request.

   Name the branch bp-<NNNN> and use the number of the original pull request.

   git fetch upstream refs/pull/1234/head:bp-1234
   git checkout bp-1234
   

3. Find the parent commit of the original pull request.

   The parent commit of the original pull request must be known in order to rebase onto a release branch. The easiest way to find this is on GitHub.

   Open the original pull request on GitHub and find the first commit in the list of commits. Select and copy the SHA for that commit. The parent of that commit can be specified by appending ~1 to the end.

4. Rebase the new branch on top of the release branch.

   • <release-branch> is the branch identified in step #1.
   • <orig-base> is the SHA identified in step #3 -- don't forget to add ~1 to the end!

   git rebase --onto <release-branch> <orig-base> bp-1234
   

   Note, release branches prior to 2014.7 will not be able to make use of rebase and must use cherry-picking instead.

5. Push the back-port branch to GitHub and open a new pull request.

   Opening a pull request for the back-port allows for the test suite and normal code-review process.

   git push -u origin bp-1234