Contributing to Salt documentation#
Ways to contribute#
Here at the Salt Project, we value all contributions, not just contributions to the code. In addition to contributing to the code, you can help the Salt Project by:
- Writing, reviewing, and revising Salt documentation, modules, and tutorials
- Opening issues (documentation issues can be opened in this repository)
- Helping with user-to-user support questions
- Spreading the word about how great Salt is
The rest of this guide will explain our toolchain and how to set up your environment to contribute to the Salt User Guide.
For additional help, see:
Overview of the toolchain#
This repository uses the following tools:
- The Salt User Guide documentation is composed in reStructured text (rST), which is a version of Markdown that is generally used in Python-based projects.
- The rST is then run through Sphinx, a static site generator that converts the rST into HTML for publication on the web.
- Sphinx applies the SaltStack Material Theme for Sphinx to render the site.
- The guide is hosted directly on GitLab using the GitLab pages feature.
- GitLab handles the CI/CD pipeline for the project.
- EditorConfig is an optional tool you can use with your preferred editor to ensure that you follow the Salt Project coding guidelines.
Overview of how to contribute to the Salt User Guide repository#
To contribute to this repository, you first need to set up your own local repository:
After this initial setup, you then need to:
- Sync local master branch with upstream master
- Edit the documentation in reStructured Text
- Preview HTML changes locally
- Open a merge request in Gitlab
Once a merge request gets approved, it can be merged. At any time, you can ask a member of the documentation team for assistance.
For local development, the following prerequisites are needed:
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:
- Official Microsoft docs on installing WSL
- Alternatively, you can download and install it from the Microsoft store, which
you can access by typing
storein the Start menu search.
Some additional helpful resources:
- Some Windows users enjoy using Windows Terminal to access the WSL command line. See Windows Terminal installation.
- If you’re using Windows Terminal and Ubuntu, see How to add Ubuntu Tab to Windows 10’s New Terminal.
- You might also want to install the Magic Monty Git Bash Prompt utility, which provides some nice Git highlighting features for quality of life. See Installing Git Bash Prompt via a Git clone.
- 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
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:
- Git BASH
- Git GUI
- Shell Integration
Fork, clone, and branch the repo#
The Salt 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. Fork the repository into your personal GitLab user workspace.
Then, clone the forked repo to your local machine:
# SSH git clone firstname.lastname@example.org:<forked-repo-path>/salt-user-guide.git # or HTTPS git clone https://gitlab.com/<forked-repo-path>/salt-user-guide.git
Before cloning your forked repo, 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.
Configure the remotes for your main upstream repository:
# Move into cloned repo cd salt-user-guide ## Choose SSH or HTTPS upstream endpoint # SSH git remote add upstream email@example.com:saltstack/open/docs/salt-user-guide.git # or HTTPS git remote add upstream https://gitlab.com/saltstack/open/docs/salt-user-guide.git
Create new branch for changes to submit:
git checkout -b my-new-feature
Configure your editor (optional)#
EditorConfig is an optional tool you can use with your preferred code/text editor to ensure that you follow the Salt Project coding and style guidelines. To enable EditorConfig, check the compatibility and configuration settings for your preferred code/text editor.
Using EditorConfig is optional for contributing to this repository, but recommended.
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 # The requirements-dev.txt file includes pre-commit and nox pip install -r requirements-dev.txt # Setup pre-commit pre-commit install
All required files should now be in place.
Here at Salt we use pre-commit, nox, and vale to make it easier for contributors to get quick feedback, for quality control, and to increase the chance that your merge request will get reviewed and merged.
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
as Make with superpowers.
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 pre-commit fails, try running it a second time. Sometimes on the first pass, pre-commit automatically fixes any errors (such as line ending characters that are weirdly added by Windows operating systems). If you run pre-commit a second time, it should pass. If it doesn’t pass again, that means you have a genuine error that you need to fix. Use the error codes and messages to troubleshoot.
Currently there is an issue with the pip-tools-compile pre-commit hook on
Windows. The details around this issue are included here:
Please ensure you export
SKIP=pip-tools-compile to skip pip-tools-compile.
What is Vale?#
vale is a tool that will automatically run from
pre-commit to enforce the
Salt Project documentation style guide and suggest general writing guidelines
when you attempt to make a git commit.
Vale can check your writing in real-time (or near-realtime) in a wide variety of editors, including plugins for:
This permits you to view errors immediately rather than having to wait until pre-commit is run when your changes are checked in. While the command-line version of vale won’t automatically make corrections for you, there is also a reasonably priced commercial version called Vale Server which does permit auto-correction (along with other features).
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.
For simplified workflow, a live-reload version of the documentation can run in the background while writing docs. To build and serve the Sphinx HTML documentation, with live-reloading on all file changes (for every save):
# Activate venv source .venv/bin/activate # On Windows, use instead: # .venv/Scripts/activate # Generate live-reload of documentation in web browser # Use CTRL+C in the terminal when done, to close the session nox -e docs
To preview how the CI tooling generates the HTML for usage, without live-reloading:
# 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
The above two approaches view the same docs output, just one is live-reloading.
If you encounter an error, you might need to re-install the requirements file. See the instructions in Set up your local preview environment.
Preview changes in GitLab Pages#
After you submit a merge request to this repo, the documentation generated by Sphinx in this repository is published via GitLab Pages. This feature allows you to share a preview of your changes with the merge approvers.
Each forked repository has their own GitLab Pages deployed website. Example format of your Gitlab pages preview URL:
To preview a GitLab Pages deployment for the main repository or a fork, do the following:
# Example URL of forked repository # GitLab Repository https://gitlab.com/<username>/salt-user-guide # Change the beginning of the URL, ending with this format # GitLab Pages https://<username>.gitlab.io/salt-user-guide
https://gitlab.io/<username> changed to
Single-branch deployment warning#
GitLab Pages will always deploy the latest branch of a repository. Keep this in mind when it comes to forks or the upstream repo, as the latest branch to be pushed to the repository will be what GitLab Pages deploys. It is not possible to have multiple branches viewable in GitLab Pages at the same time for a repository.