Contributing

There is a great need for contributions to Salt and patches are welcome! The goal here is to make contributions clear, make sure there is a trail for where the code has come from, and most importantly, to give credit where credit is due!

There are a number of ways to contribute to Salt development, including (but not limited to):

If this or other Salt documentation is unclear, please review Writing Salt Documentation. PRs are welcome!

Quickstart

If you just want to get started before reading the rest of this guide, you can get the process started by running the following:

python3 -m pip install --user pre-commit
git clone --origin upstream https://github.com/saltstack/salt.git
cd salt
pre-commit install

While those commands are running, finish reading the rest of this guide.

Pre-commit

To reduce friction during the development process, SaltStack uses pre-commit. This tool adds pre-commit hooks to git to automate several processes that used to be manual. Rather than having to remember to run several different tools before you commit, you only have to run git commit, and you will be notified about style and lint issues before you ever open a PR.

Warning

Currently there is an issue with the pip-tools-compile pre-commit hook on windows. The details around this issue are included here: https://github.com/saltstack/salt/issues/56642. Please ensure you export SKIP=pip-tools-compile to skip pip-tools-compile.

Salt Coding Style

After the 3000 release, SaltStack is joining the ranks of projects in adopting the Black code formatter in order to ease the adoption of a unified code formatting style.

Where Black is silent, SaltStack has its own coding style guide that informs contributors on various style points. Please review the Salt Coding Style documentation for information about Salt's particular coding patterns.

Within the Salt Coding Style documentation, there is a section about running Salt's .testing.pylintrc file. SaltStack recommends running the .testing.pylintrc file on any files you are changing with your code contribution before submitting a pull request to Salt's repository.

If you've installed pre-commit, this will automatically happen before each commit. Otherwise, see the Linting documentation for more information.

New Features

Feature requests through Salt go through a multi-stage process.

All features are added to major releases only. Salt does not accept feature additions in bug-fix branches. Therefore, all feature work is done exclusively in the develop branch.

To formally propose a new feature, the proposal must take the form of an RFC. To create an RFC, copy the template file found in the rfcs/ directory of the Salt codebase and fill the outline with the reasoning for the new feature and with implementation details.

Upon submitting the written RFC via a pull-request, it will be reviewed by the core development team as well as the community. Once discussed and agreed upon, the RFC may be merged.

A merged RFC indicates that a feature has been accepted and will be added to an upcoming release of Salt.

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 saltstack/salt on GitHub.

  2. Make a local clone of your fork. (Skip this step if you followed the Quickstart)

    git clone git@github.com:my-account/salt.git
    cd salt
    
  3. Add saltstack/salt as a git remote.

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

    If you followed the Quickstart, you'll add your own remote instead

    git remote add my-account git@github.com:my-account/salt.git
    
  4. Create a new branch in your clone.

    Note

    A branch should have one purpose. For example, "Fix bug X," or "Add feature Y". Multiple unrelated fixes and/or features should be isolated into separate branches.

    git fetch upstream
    git checkout -b fix-broken-thing upstream/master
    
  5. Edit and commit changes to your branch.

    vim path/to/file1 path/to/file2 tests/test_file1.py tests/test_file2.py
    git diff
    git add path/to/file1 path/to/file2
    git commit
    

    Write a short, descriptive commit title and a longer commit message if necessary. Use an imperative style for the title.

    GOOD

    Fix broken things in file1 and file2
    
    Fixes #31337
    
    We needed to make this change because the underlying dependency
    changed. Now this uses the up-to-date API.
    
    # Please enter the commit message for your changes. Lines starting
    # with '#' will be ignored, and an empty message aborts the commit.
    # On branch fix-broken-thing
    # Changes to be committed:
    #       modified:   path/to/file1
    #       modified:   path/to/file2
    

    BAD

    Fixes broken things
    
    # Please enter the commit message for your changes. Lines starting
    # with '#' will be ignored, and an empty message aborts the commit.
    # On branch fix-broken-thing
    # Changes to be committed:
    #       modified:   path/to/file1
    #       modified:   path/to/file2
    

    Taking a few moments to explain why you made a change will save time and effort in the future when others come to investigate a change. A clear explanation of why something changed can help future developers avoid introducing bugs, or breaking an edge case.

    Note

    If your change fixes a bug or implements a feature already filed in the issue tracker, be sure to reference the issue number in the commit message body.

    If you get stuck, there are many introductory Git resources on https://help.github.com/en.

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

    git push -u origin fix-broken-thing
    

    or

    git push -u origin add-cool-feature
    

    Note

    You may want to rebase before pushing to work out any potential conflicts:

    git fetch upstream
    git rebase upstream/master fix-broken-thing
    git push -u origin fix-broken-thing
    

    If you do rebase, and the push is rejected with a (non-fast-forward) comment, then run git status. You will likely see a message about the branches diverging:

    On branch fix-broken-thing
    Your branch and 'origin/fix-broken-thing' have diverged,
    and have 1 and 2 different commits each, respectively.
      (use "git pull" to merge the remote branch into yours)
    nothing to commit, working tree clean
    

    Do NOT perform a git pull or git merge here. Instead, add --force-with-lease to the end of the git push command to get the changes pushed to your fork. Pulling or merging, while they will resolve the non-fast-forward issue, will likely add extra commits to the pull request which were not part of your changes.

  7. Find the branch on your GitHub salt fork.

    https://github.com/my-account/salt/branches/fix-broken-thing

  8. Open a new pull request.

    Click on Pull Request on the right near the top of the page,

    https://github.com/my-account/salt/pull/new/fix-broken-thing

    1. Choose master as the base Salt branch.

    2. Review that the proposed changes are what you expect.

    3. Write a descriptive comment. If you added good information to your git commit message, they will already be present here. Include links to related issues (e.g. 'Fixes #31337.') in the comment field.

    4. Click Create pull request.

  9. Salt project members will review your pull request and automated tests will run on it.

    If you recognize any test failures as being related to your proposed changes or if a reviewer asks for modifications:

    1. Make the new changes in your local clone on the same local branch.

    2. Push the branch to GitHub again using the same commands as before.

    3. New and updated commits will be added to the pull request automatically.

    4. Feel free to add a comment to the discussion.

Note

Jenkins

Pull request against saltstack/salt are automatically tested on a variety of operating systems and configurations. On average these tests take a couple of hours. Depending on your GitHub notification settings you may also receive an email message about the test results.

Test progress and results can be found at https://jenkinsci.saltstack.com/.

Salt's Branch Topology

Salt will only have one active branch - master. This will include bug fixes, features and CVE “Common Vulnerabilities and Exposures”.

The release will be cut from the master when the time comes for a new release, which should be every 3 to 4 months.

To be able to merge code:

  1. The code must have a well-written test. Note that you are only expected to write tests for what you did, not the whole modules or function.

  2. All tests must pass.

The SaltStack employee that reviews your pull request might request changes or deny the pull request for various reasons.

Salt uses a typical branch strategy - master is the next expected release. Code should only make it to master once it's production ready. This means that typical changes (fixes, features) should have accompanying tests.

Closing GitHub issues from commits

SaltStack encourages using the magic keywords to close a GitHub issue. These should appear in the commit message text directly.

Release Naming Convention

A new convention will start when Salt releases Salt 3000. Every new release name will increment by one ‘Salt last_release_number + 1’.

This naming convention is very different from past releases, which was 'YYYY.MM.PATCH'.

Handling CVE

If a CVE is discovered, Salt will create a new release that only contains the tests and patch for the CVE. This method should improve the upgrade process by reducing the chances of breaking something.

Backporting Pull Requests

On rare occasions, a serious bug will be found in the middle of a release cycle. These bugs will require a point release. Contributors should still submit fixes directly to master, but they should also call attention to the fact that it addresses a critical issue and will need to be back-ported.

Keeping Salt Forks in Sync

Salt advances 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 git@github.com: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 master branch.

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

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

    • Run git pull --rebase origin master 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 master 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 master
    
  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.

Issue and Pull Request Labeling System

SaltStack uses several labeling schemes to help facilitate code contributions and bug resolution. See the Labels and Milestones documentation for more information.

Mentionbot

SaltStack runs a mention-bot which notifies contributors who might be able to help review incoming pull-requests based on their past contribution to files which are being changed.

If you do not wish to receive these notifications, please add your GitHub handle to the blacklist line in the .mention-bot file located in the root of the Salt repository.

Bootstrap Script Changes

Salt's Bootstrap Script, known as bootstrap-salt.sh in the Salt repo, has its own repository, contributing guidelines, and release cadence.

All changes to the Bootstrap Script should be made to salt-bootstrap repo. Any pull requests made to the bootstrap-salt.sh file in the Salt repository will be automatically overwritten upon the next stable release of the Bootstrap Script.

For more information on the release process or how to contribute to the Bootstrap Script, see the Bootstrap Script's Contributing Guidelines.