Contributions are what make the open source community such an amazing place to learn, inspire, and create in. Any contributions you make are greatly appreciated!
Have pre-requisites completed:
Fork the project
git cloneyour fork locally
Create your feature branch (ex.
git checkout -b amazing-feature)
Setup your local development environment
# setup venv python3 -m venv .venv source .venv/bin/activate pip install -U pip setuptools wheel pre-commit nox # pre-commit configuration pre-commit install
Commit your changes (ex.
git commit -m 'Add some amazing-feature')
Push to the branch (ex.
git push origin amazing-feature)
Open a pull request
For the full details, see below.
Ways to contribute#
We value all contributions, not just contributions to the code. In addition to contributing to the code, you can help the project by:
Writing, reviewing, and revising documentation, modules, and tutorials
Opening issues on bugs, feature requests, or docs
Spreading the word about how great this project is
The rest of this guide will explain our toolchain and how to set up your environment to contribute to the project.
Overview of how to contribute to this repository#
To contribute to this repository, you first need to set up your own local repository:
After this initial setup, you then need to:
Edit the documentation in reStructured Text
Open a PR
Once a merge request gets approved, it can be merged!
For local development, the following prerequisites are needed:
Windows 10 users#
For the best experience, when contributing from a Windows OS to projects using
Python-based tools like
pre-commit, we recommend setting up Windows Subsystem
for Linux (WSL), with the
latest version being WSLv2.
The following gists on GitHub have been consulted with success for several contributors:
A list of PowerShell commands in a gist to Enable WSL and Install Ubuntu 20.04
Ensure you also read the comment thread below the main content for additional guidance about using Python on the WSL instance.
We recommend Installing Chocolatey on Windows 10 via PowerShell w/ Some Starter Packages.
microsoft-windows-terminal, and other helpful tools via
the awesome Windows package management tool, Chocolatey.
choco install git easily installs
git for a good Windows-dev experience.
git package page on Chocolatey, the following are installed:
Fork, clone, and branch the repo#
This project uses the fork and branch Git workflow. For an overview of this method, see Using the Fork-and-Branch Git Workflow.
First, create a new fork into your personal user space.
Then, clone the forked repo to your local machine.
# SSH or HTTPS git clone <forked-repo-path>/heist-salt.git
Before cloning your forked repo when using SSH, you need to create an SSH key so that your local Git repository can authenticate to the GitLab remote server. See GitLab and SSH keys for instructions, or Connecting to GitHub with SSH.
Configure the remotes for your main upstream repository:
# Move into cloned repo cd heist-salt # Choose SSH or HTTPS upstream endpoint git remote add upstream git-or-https-repo-you-forked-from
Create new branch for changes to submit:
git checkout -b amazing-feature
Set up your local preview environment#
If you are not on a Linux machine, you need to set up a virtual environment to preview your local changes and ensure the prerequisites are met for a Python virtual environment.
From within your local copy of the forked repo:
# Setup venv python3 -m venv .venv # If Python 3.6+ is in path as 'python', use the following instead: # python -m venv .venv # Activate venv source .venv/bin/activate # On Windows, use instead: # .venv/Scripts/activate # Install required python packages to venv pip install -U pip setuptools wheel pre-commit nox pip install -r requirements.txt # Setup pre-commit pre-commit install
nox handles Sphinx requirements and plugins for you, always ensuring your
local packages are the needed versions when building docs. You can think of it
Make with superpowers. It is also used to execute the rest of the test
What is pre-commit?#
pre-commit is a tool that will automatically run
local tests when you attempt to make a git commit. To view what tests are run,
you can view the
.pre-commit-config.yaml file at the root of the
One big benefit of pre-commit is that auto-corrective measures can be done to files that have been updated. This includes Python formatting best practices, proper file line-endings (which can be a problem with repository contributors using differing operating systems), and more.
If an error is found that cannot be automatically fixed, error output will help point you to where an issue may exist.
Sync local master branch with upstream master#
If needing to sync feature branch with changes from upstream master, do the following:
This will need to be done in case merge conflicts need to be resolved locally before a merge to master in the upstream repo.
git checkout master git fetch upstream git pull upstream master git push origin master git checkout my-new-feature git merge master
Preview HTML changes locally#
To ensure that the changes you are implementing are formatted correctly, you should preview a local build of your changes first. To preview the changes:
# Activate venv source .venv/bin/activate # On Windows, use instead: # .venv/Scripts/activate # Generate HTML documentation with nox nox -e 'docs-html(clean=False)' # Sphinx website documentation is dumped to docs/_build/html/* # You can view this locally # firefox example firefox docs/_build/html/index.html
If you encounter an error, Sphinx may be pointing out formatting errors
that need to be resolved in order for
nox to properly generate the docs.
# View all nox targets nox -l # Run tests nox -e 'tests'
This project is a
pop project which makes use of
pytest plugin. For more information on
pytest-pop, and writing tests