saltstack/salt
1
0
Fork 0
mirror of https://github.com/saltstack/salt.git synced 2025-04-17 10:10:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Merge pull request #63032 from barbaricyawps/import-readme-contributing

Browse source 
[DOCS ONLY] Improve README and CONTRIBUTING guide (from internal doc audit)
This commit is contained in:
Gareth J. Greenaway 2022-12-13 14:52:48 -08:00 • committed by GitHub
commit 3e7678af87
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
8 changed files with 286 additions and 570 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

319
CONTRIBUTING.rst
View file

@ -2,34 +2,33 @@
Contributing
============
So you want to contribute to the Salt project? Excellent! You can help
in a number of ways:
- Using Salt and opening well-written bug reports.
- Joining a `working group <https://github.com/saltstack/community>`__.
- Answering questions on `irc <https://web.libera.chat/#salt>`__,
- Use Salt and open well-written bug reports.
- Join a `working group <https://github.com/saltstack/community>`__.
- Answer questions on `irc <https://web.libera.chat/#salt>`__,
the `community Slack <https://join.slack.com/t/saltstackcommunity/shared_invite/zt-3av8jjyf-oBQ2M0vhXOhJpNpRkPWBvg>`__,
the `salt-users mailing
list <https://groups.google.com/forum/#!forum/salt-users>`__,
`Server Fault <https://serverfault.com/questions/tagged/saltstack>`__,
or `r/saltstack on Reddit <https://www.reddit.com/r/saltstack/>`__.
- Fixing bugs.
- `Enhancing the documentation <https://docs.saltproject.io/en/master/topics/development/conventions/documentation.html#salt-docs>`__.
- Providing workarounds, patches, or other code without tests.
- Telling other people about problems you solved using Salt.
- Fix bugs.
- `Improve the documentation <https://saltstack.gitlab.io/open/docs/docs-hub/topics/contributing.html>`__.
- Provide workarounds, patches, or other code without tests.
- Tell other people about problems you solved using Salt.
If you’d like to update docs or fix an issue, you’re going to need the
If you'd like to update docs or fix an issue, you're going to need the
Salt repo. The best way to contribute is using
`Git <https://git-scm.com/>`__.
Environment Setup
-----------------
To hack on Salt or the docs you’re going to need to set up your
development environment. If you already have a workflow that you’re
Environment setup
=================
To hack on Salt or the docs you're going to need to set up your
development environment. If you already have a workflow that you're
comfortable with, you can use that, but otherwise this is an opinionated
guide for setting up your dev environment. Follow these steps and you’ll
guide for setting up your dev environment. Follow these steps and you'll
end out with a functioning dev environment and be able to submit your
first PR.
@ -44,16 +43,15 @@ more about Git. One popular resource is the free online book `Learn Git
in a Month of
Lunches <https://www.manning.com/books/learn-git-in-a-month-of-lunches>`__.
pyenv, Virtual Environments, and You
----------------------------------------
pyenv, Virtual Environments, and you
------------------------------------
We recommend `pyenv <https://github.com/pyenv/pyenv>`__, since it allows
installing multiple different Python versions, which is important for
testing Salt across all the versions of Python that we support.
On Linux
~~~~~~~~
^^^^^^^^
Install pyenv:
::
@ -63,8 +61,7 @@ Install pyenv:
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
On Mac
~~~~~~
^^^^^^
Install pyenv using brew:
::
@ -93,11 +90,11 @@ version of Python:
pyenv install 3.7.0
If that fails, don’t panic! You’re probably just missing some build
If that fails, don't panic! You're probably just missing some build
dependencies. Check out `pyenv common build
problems <https://github.com/pyenv/pyenv/wiki/Common-build-problems>`__.
Now that you’ve got your version of Python installed, you can create a
Now that you've got your version of Python installed, you can create a
new virtual environment with this command:
::
@ -110,13 +107,13 @@ Then activate it:
pyenv activate salt
Sweet! Now you’re ready to clone Salt so you can start hacking away! If
Sweet! Now you're ready to clone Salt so you can start hacking away! If
you get stuck at any point, check out the resources at the beginning of
this guide. IRC and Slack are particularly helpful places to go.
Get The Source!
~~~~~~~~~~~~~~~
Get the source!
---------------
Salt uses the fork and clone workflow for Git contributions. See `Using
the Fork-and-Branch Git
Workflow <https://blog.scottlowe.org/2015/01/27/using-fork-branch-git-workflow/>`__
@ -130,13 +127,13 @@ Clones are so shallow. Well, this one is anyway:
git clone --depth=1 --origin salt https://github.com/saltstack/salt.git
This creates a shallow clone of Salt, which should be fast. Most of the
time that’s all you’ll need, and you can start building out other
time that's all you'll need, and you can start building out other
commits as you go. If you *really* want all 108,300+ commits you can
just run ``git fetch --unshallow``. Then go make a sandwich because it’s
just run ``git fetch --unshallow``. Then go make a sandwich because it's
gonna be a while.
You’re also going to want to head over to GitHub and create your own
`fork of Salt <https://github.com/saltstack/salt/fork>`__. Once you’ve
You're also going to want to head over to GitHub and create your own
`fork of Salt <https://github.com/saltstack/salt/fork>`__. Once you've
got that set up you can add it as a remote:
::
@ -144,16 +141,16 @@ got that set up you can add it as a remote:
git remote add yourname <YOUR SALT REMOTE>
If you use your name to refer to your fork, and ``salt`` to refer to the
official Salt repo you’ll never get ``upstream`` or ``origin`` confused.
official Salt repo you'll never get ``upstream`` or ``origin`` confused.
.. note::
Each time you start work on a new issue you should fetch the most recent
changes from ``salt/upstream``.
``pre-commit`` and ``nox`` Setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Set up ``pre-commit`` and ``nox``
---------------------------------
Here at Salt we use `pre-commit <https://pre-commit.com/>`__ and
`nox <https://nox.thea.codes/en/stable/>`__ to make it easier for
contributors to get quick feedback, for quality control, and to increase
@ -177,14 +174,12 @@ others. You can easily install them in your virtualenv with:
Please ensure you export ``SKIP=pip-tools-compile`` to skip pip-tools-compile.
Now before each commit, it will ensure that your code at least *looks*
right before you open a pull request. And with that step, it’s time to
right before you open a pull request. And with that step, it's time to
start hacking on Salt!
.. _imagemagick-setup:
``imagemagick`` Setup
~~~~~~~~~~~~~~~~~~~~~
Set up imagemagick
------------------
One last prerequisite is to have ``imagemagick`` installed, as it is required
by Sphinx for generating the HTML documentation.
@ -199,17 +194,17 @@ by Sphinx for generating the HTML documentation.
sudo apt install imagemagick
Salt Issues
-----------
Salt issues
===========
Create Your Own
~~~~~~~~~~~~~~~
Create your own
---------------
Perhaps you’ve come to this guide because you found a problem in Salt,
and you’ve diagnosed the cause. Maybe you need some help figuring out
Perhaps you've come to this guide because you found a problem in Salt,
and you've diagnosed the cause. Maybe you need some help figuring out
the problem. In any case, creating quality bug reports is a great way to
contribute to Salt even if you lack the skills, time, or inclination to
fix it yourself. If that’s the case, head on over to `Salt’s issue
fix it yourself. If that's the case, head on over to `Salt's issue
tracker on
GitHub <https://github.com/saltstack/salt/issues/new/choose>`__.
@ -228,20 +223,20 @@ In a nutshell:
- **Minimum**: All of the **extra** information has been removed. Will
2 or 3 lines of master/minion config still exhibit the behavior?
- **Complete**: Minimum also means complete. If your example is missing
information, then it’s not complete. Salt, Python, and OS versions
information, then it's not complete. Salt, Python, and OS versions
are all bits of information that make your example complete. Have you
provided the commands that you ran?
- **Verifiable**: Can someone take your report and reproduce it?
Slow is smooth, and smooth is fast - it may feel like you’re taking a
long time to create your issue if you’re creating a proper MCVE, but a
Slow is smooth, and smooth is fast - it may feel like you're taking a
long time to create your issue if you're creating a proper MCVE, but a
MCVE eliminates back and forth required to reproduce/verify the issue so
someone can actually create a fix.
Pick An Issue
~~~~~~~~~~~~~
Pick an issue
-------------
If you don’t already have an issue in mind, you can search for `help
If you don't already have an issue in mind, you can search for `help
wanted <https://github.com/saltstack/salt/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22>`__
issues. If you also search for `good first
issue <https://github.com/saltstack/salt/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22+label%3A%22good+first+issue%22>`__
@ -249,17 +244,17 @@ then you should be able to find some issues that are good for getting
started contributing to Salt. `Documentation
issues <https://github.com/saltstack/salt/issues?q=is%3Aissue+is%3Aopen+label%3Adocumentation+>`__
are also good starter issues. When you find an issue that catches your
eye (or one of your own), it’s a good idea to comment on the issue and
mention that you’re working on it. Good communication is key to
collaboration - so if you don’t have time to complete work on the issue,
eye (or one of your own), it's a good idea to comment on the issue and
mention that you're working on it. Good communication is key to
collaboration - so if you don't have time to complete work on the issue,
just leaving some information about when you expect to pick things up
again is a great idea!
Hacking Away
------------
Hacking away
============
Salt, Tests, Documentation, and You
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Salt, tests, documentation, and you
-----------------------------------
Before approving code contributions, Salt requires:
@ -269,31 +264,81 @@ Before approving code contributions, Salt requires:
Documentation fixes just require correct documentation.
What If I Don’t Write Tests or Docs?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
What if I don't write tests or docs?
------------------------------------
If you aren’t into writing documentation or tests, we still welcome your
If you aren't into writing documentation or tests, we still welcome your
contributions! But your PR will be labeled ``Needs Testcase`` and
``Help Wanted`` until someone can get to write the tests/documentation.
Of course, if you have a desire but just lack the skill we are more than
happy to collaborate and help out! There’s the `documentation working
group <https://github.com/saltstack/docs-hub>`__ and the `testing
working
group <https://github.com/saltstack/community/tree/master/working_groups/wg-Testing>`__.
happy to collaborate and help out! There's the `documentation working
group <https://saltstack.gitlab.io/open/docs/docs-hub/topics/home.html>`__
and the `testing working group <https://github.com/saltstack/community/tree/master/working_groups/wg-Testing>`__.
We also regularly stream our test clinic `live on
Twitch <https://www.twitch.tv/saltprojectoss>`__ every Tuesday afternoon
and Thursday morning, Central Time. If you’d like specific help with
and Thursday morning, Central Time. If you'd like specific help with
tests, bring them to the clinic. If no community members need help, you
can also just watch tests written in real time.
.. _docs-building:
Documentation
~~~~~~~~~~~~~
-------------
Salt uses both docstrings, as well as normal reStructuredText files in
the ``salt/doc`` folder for documentation. Sphinx is used to generate the
documentation, and does require :ref:`setting up imagemagick on your OS.<imagemagick-setup>`
documentation, and does require ``imagemagick``. See `Set up imagemagick`_ for
more information.
Before submitting a documentation PR, it helps to first build the Salt docs
locally on your machine and preview them. Local previews helps you:
- Debug potential documentation output errors before submitting a PR.
- Saves you time by not needing to use the Salt CI/CD test suite to debug, which takes
more than 30 minutes to run on a PR.
- Ensures the final output looks the way you intended it to look.
To set up your local environment to preview the core Salt and module
documentation:
#. Install the documentation dependencies. For example, on Ubuntu:
::
sudo apt-get update
sudo apt-get install -y enchant-2 git gcc imagemagick make zlib1g-dev libc-dev libffi-dev g++ libxml2 libxml2-dev libxslt-dev libcurl4-openssl-dev libssl-dev libgnutls28-dev xz-utils inkscape
#. Navigate to the folder where you store your Salt repository and remove any
`.nox` directories that might be in that folder:
::
rm -rf .nox
#. Install `pyenv` for the version of Python needed to run the docs. As of the
time of writing, the Salt docs theme is not compatible with Python 3.10, so
you'll need to run 3.9 or earlier. For example:
::
pyenv install 3.7.15
pyenv virtualenv 3.7.15 salt-docs
echo 'salt-docs' > .python-version
#. Activate `pyenv` if it's not auto-activated:
::
pyenv exec pip install -U pip setuptools wheel
#. Install `nox` into your pyenv environment, which is the utility that will
build the Salt documentation:
::
pyenv exec pip install nox
Since we use ``nox``, you can build your docs and view them in your browser
with this one-liner:
@ -301,9 +346,9 @@ with this one-liner:
python -m nox -e 'docs-html(compress=False, clean=False)'; cd doc/_build/html; python -m webbrowser http://localhost:8000/contents.html; python -m http.server
The first time this will take a while because there are a *lot* of
modules. Maybe you should go grab some dessert if you already finished
that sandwich. But once Sphinx is done building the docs, python should
The first time you build the docs, it will take a while because there are a
*lot* of modules. Maybe you should go grab some dessert if you already finished
that sandwich. But once nox and Sphinx are done building the docs, python should
launch your default browser with the URL
http://localhost:8000/contents.html. Now you can navigate to your docs
and ensure your changes exist. If you make changes, you can simply run
@ -314,20 +359,29 @@ this:
cd -; python -m nox -e 'docs-html(compress=False, clean=False)'; cd doc/_build/html; python -m http.server
And then refresh your browser to get your updated docs. This one should
be quite a bit faster since Sphinx won’t need to rebuild everything.
be quite a bit faster since Sphinx won't need to rebuild everything.
Alternatively, you could build the docs on your local machine and then preview
the build output. To build the docs locally:
::
pyenv exec nox -e 'docs-html(compress=False, clean=True)'
The output from this command will put the preview files in: ``doc > _build > html``.
If your change is a docs-only change, you can go ahead and commit/push
your code and open a PR. You can indicate that it’s a docs-only change by
adding ``[Documentation]`` to the title of your PR. Otherwise you’ll
your code and open a PR. You can indicate that it's a docs-only change by
adding ``[Documentation]`` to the title of your PR. Otherwise, you'll
want to write some tests and code.
Running Development Salt
~~~~~~~~~~~~~~~~~~~~~~~~
Running development Salt
------------------------
Note: If you run into any issues in this section, check the
Troubleshooting section.
If you’re going to hack on the Salt codebase you’re going to want to be
If you're going to hack on the Salt codebase you're going to want to be
able to run Salt locally. The first thing you need to do is install Salt
as an editable pip install:
@ -337,7 +391,7 @@ as an editable pip install:
This will let you make changes to Salt without having to re-install it.
After all of the dependencies and Salt are installed, it’s time to set
After all of the dependencies and Salt are installed, it's time to set
up the config for development. Typically Salt runs as ``root``, but you
can specify which user to run as. To configure that, just copy the
master and minion configs. We have .gitignore setup to ignore the
@ -397,35 +451,35 @@ from the minion instead:
salt-call -c local/etc/salt test.version
Note that you’re running ``salt-call`` instead of ``salt``, and you’re
not specifying the minion (``\*``), but if you’re running the dev
Note that you're running ``salt-call`` instead of ``salt``, and you're
not specifying the minion (``\*``), but if you're running the dev
version then you still will need to pass in the config dir. Now that
you’ve got Salt running, you can hack away on the Salt codebase!
you've got Salt running, you can hack away on the Salt codebase!
If you need to restart Salt for some reason, if you’ve made changes and
they don’t appear to be reflected, this is one option:
If you need to restart Salt for some reason, if you've made changes and
they don't appear to be reflected, this is one option:
::
kill -INT $(pgrep salt-master)
kill -INT $(pgrep salt-minion)
If you’d rather not use ``kill``, you can have a couple of terminals
If you'd rather not use ``kill``, you can have a couple of terminals
open with your salt virtualenv activated and omit the ``--daemon``
argument. Salt will run in the foreground, so you can just use ctrl+c to
quit.
Test First? Test Last? Test Meaningfully!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Test first? Test last? Test meaningfully!
-----------------------------------------
You can write tests first or tests last, as long as your tests are
meaningful and complete! *Typically* the best tests for Salt are going
to be unit tests. Testing is `a whole topic on its
own <https://docs.saltproject.io/en/master/topics/tutorials/writing_tests.html>`__,
But you may also want to write functional or integration tests. You’ll
But you may also want to write functional or integration tests. You'll
find those in the ``salt/tests`` directory.
When you’re thinking about tests to write, the most important thing to
When you're thinking about tests to write, the most important thing to
keep in mind is, “What, exactly, am I testing?” When a test fails, you
should know:
@ -433,21 +487,21 @@ should know:
- Why did it fail?
- As much as possible, what do I need to do to fix this failure?
If you can’t answer those questions then you might need to refactor your
If you can't answer those questions then you might need to refactor your
tests.
When you’re running tests locally, you should make sure that if you
remove your code changes your tests are failing. If your tests *aren’t*
failing when you haven’t yet made changes, then it’s possible that
you’re testing the wrong thing.
When you're running tests locally, you should make sure that if you
remove your code changes your tests are failing. If your tests *aren't*
failing when you haven't yet made changes, then it's possible that
you're testing the wrong thing.
But whether you adhere to TDD/BDD, or you write your code first and your
tests last, ensure that your tests are meaningful.
Running Tests
^^^^^^^^^^^^^
As previously mentioned, we use ``nox``, and that’s how we run our
Running tests
-------------
As previously mentioned, we use ``nox``, and that's how we run our
tests. You should have it installed by this point but if not you can
install it with this:
@ -461,26 +515,26 @@ Now you can run your tests:
python -m nox -e "pytest-3.7(coverage=False)" -- tests/unit/cli/test_batch.py
It’s a good idea to install
It's a good idea to install
`espeak <https://github.com/espeak-ng/espeak-ng>`__ or use ``say`` on
Mac if you’re running some long-running tests. You can do something like
Mac if you're running some long-running tests. You can do something like
this:
::
python -m nox -e "pytest-3.7(coverage=False)" -- tests/unit/cli/test_batch.py; espeak "Tests done, woohoo!"
That way you don’t have to keep monitoring the actual test run.
That way you don't have to keep monitoring the actual test run.
Changelog and Commit!
~~~~~~~~~~~~~~~~~~~~~
Changelog and commit!
---------------------
When you write your commit message you should use imperative style. Do
this:
Add frobnosticate capability
Don’t do this:
Don't do this:
Added frobnosticate capability
@ -495,44 +549,44 @@ instanch, if you fixed issue 123, you would do:
echo "Made sys.doc inform when no minions return" > changelog/123.fixed
And that’s all that would go into your file. When it comes to your
commit message, it’s usually a good idea to add other information, such as
And that's all that would go into your file. When it comes to your
commit message, it's usually a good idea to add other information, such as
- What does a reviewer need to know about the change that you made?
- If someone isn’t an expert in this area, what will they need to know?
- If someone isn't an expert in this area, what will they need to know?
This will also help you out, because when you go to create the PR it
will automatically insert the body of your commit messages.
PR Time!
--------
Once you’ve done all your dev work and tested locally, you should check
Pull request time!
------------------
Once you've done all your dev work and tested locally, you should check
out our `PR
guidelines <https://docs.saltproject.io/en/master/topics/development/pull_requests.html>`__.
After you read that page, it’s time to `open a new
After you read that page, it's time to `open a new
PR <https://github.com/saltstack/salt/compare>`__. Fill out the PR
template - you should have updated or created any necessary docs, and
written tests if you’re providing a code change. When you submit your
written tests if you're providing a code change. When you submit your
PR, we have a suite of tests that will run across different platforms to
help ensure that no known bugs were introduced.
Now What?
~~~~~~~~~
You’ve made your changes, added documentation, opened your PR, and have
Now what?
---------
You've made your changes, added documentation, opened your PR, and have
passing tests… now what? When can you expect your code to be merged?
When you open your PR, a reviewer will get automatically assigned. If
your PR is submitted during the week you should be able to expect some
kind of communication within that business day. If your tests are
passing and we’re not in a code freeze, ideally your code will be merged
that day. If you haven’t heard from your assigned reviewer, ping them on
GitHub, `irc <https://web.libera.chat/#salt>`__, or Community Slack.
passing and we're not in a code freeze, ideally your code will be merged
that week or month. If you haven't heard from your assigned reviewer, ping them
on GitHub, `irc <https://web.libera.chat/#salt>`__, or Community Slack.
It’s likely that your reviewer will leave some comments that need
It's likely that your reviewer will leave some comments that need
addressing - it may be a style change, or you forgot a changelog entry,
or need to update the docs. Maybe it’s something more fundamental -
or need to update the docs. Maybe it's something more fundamental -
perhaps you encountered the rare case where your PR has a much larger
scope than initially assumed.
@ -542,22 +596,23 @@ open for a significant period of time it may be worth rebasing your
changes on the most recent changes to Salt. If you need help, the
previously linked Git resources will be valuable.
But if, for whatever reason, you’re not interested in driving your PR to
completion then just note that in your PR. Something like, “I’m not
But if, for whatever reason, you're not interested in driving your PR to
completion then just note that in your PR. Something like, “I'm not
interested in writing docs/tests, I just wanted to provide this fix -
someone else will need to complete this PR.” If you do that then we’ll
someone else will need to complete this PR.” If you do that then we'll
add a “Help Wanted” label and someone will be able to pick up the PR,
make the required changes, and it can eventually get merged in.
In any case, now that you have a PR open, congrats! You’re a Salt
In any case, now that you have a PR open, congrats! You're a Salt
developer! You rock!
Troubleshooting
---------------
===============
zmq.core.error.ZMQError
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
Once the minion starts, you may see an error like the following::
::
@ -576,9 +631,9 @@ length of this path. This can be done in a couple different ways:
NOTE: The socket path is limited to 107 characters on Solaris and Linux,
and 103 characters on BSD-based systems.
No permissions to access …
~~~~~~~~~~~~~~~~~~~~~~~~~~
No permissions to access ...
----------------------------
If you forget to pass your config path to any of the ``salt*`` commands,
you might see
@ -589,9 +644,9 @@ you might see
Just pass ``-c local/etc/salt`` (or whatever you named it)
File descriptor limit
~~~~~~~~~~~~~~~~~~~~~
File descriptor limit
---------------------
You might need to raise your file descriptor limit. You can check it
with:
@ -607,12 +662,12 @@ If the value is less than 3072, you should increase it with:
# For c-shell:
limit descriptors 3072
Pygit2 or other dependency install fails
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Pygit2 or other dependency install fails
----------------------------------------
You may see some failure messages when installing requirements. You can
directly access your nox environment and possibly install pygit (or
other dependency) that way. When you run nox, you’ll see a message like
other dependency) that way. When you run nox, you'll see a message like
this:
::

113
README.rst
View file

@ -36,47 +36,87 @@
* `Latest Salt Documentation`_
* `Open an issue`_ (bug report, feature request, etc.)
*Salt is the world’s fastest, most intelligent and scalable automation*
*Salt is the world's fastest, most intelligent and scalable automation*
*engine.*
About Salt
==========
Built on Python, Salt is an event-driven automation tool and framework to
deploy, configure, and manage complex IT systems. Use Salt to automate common
infrastructure administration tasks and ensure that all the components of your
infrastructure are operating in a consistent desired state.
Built on python, Salt uses simple and human-readable YAML combined with
event-driven automation to deploy and configure complex IT systems. In addition
to leveling-up `vRealize Automation SaltStack Config`_, Salt can be found under
the hood of products from Juniper, Cisco, Cloudflare, Nutanix, SUSE, and Tieto,
to name a few.
Salt has many possible uses, including configuration management, which involves:
About SaltStack
===============
* Managing operating system deployment and configuration.
* Installing and configuring software applications and services.
* Managing servers, virtual machines, containers, databases, web servers,
network devices, and more.
* Ensuring consistent configuration and preventing configuration drift.
`SaltStack was acquired by VMware in 2020 <https://www.vmware.com/company/acquisitions/saltstack.html>`_.
Salt Project remains an open source ecosystem that VMware supports and
contributes to.
Salt is ideal for configuration management because it is pluggable,
customizable, and plays well with many existing technologies. Salt enables you
to deploy and manage applications that use any tech stack running on nearly any
`operating system <https://docs.saltproject.io/salt/install-guide/en/latest/topics/salt-supported-operating-systems.html>`_,
including different types of network devices such as switches and routers from a
variety of vendors.
Download Salt
=============
In addition to configuration management Salt can also:
* Automate and orchestrate routine IT processes, such as common required tasks
for scheduled server downtimes or upgrading operating systems or applications.
* Create self-aware, self-healing systems that can automatically respond to
outages, common administration problems, or other important events.
About our sponsors
==================
Salt powers VMware's `vRealize Automation SaltStack Config`_, and can be found
under the hood of products from Juniper, Cisco, Cloudflare, Nutanix, SUSE, and
Tieto, to name a few.
The original sponsor of our community, SaltStack, was `acquired by VMware in 2020 <https://www.vmware.com/company/acquisitions/saltstack.html>`_.
The Salt Project remains an open source ecosystem that VMware supports and
contributes to. VMware ensures the code integrity and quality of the Salt
modules by acting as the official sponsor and manager of the Salt project. Many
of the core Salt Project contributors are also VMware employees. This team
carefully reviews and enhances the Salt modules to ensure speed, quality, and
security.
Download and install Salt
=========================
Salt is tested and packaged to run on CentOS, Debian, RHEL, Ubuntu, MacOS,
Windows, and more. Download Salt and get started now.
Windows, and more. Download Salt and get started now. See
`supported operating systems <https://docs.saltproject.io/salt/install-guide/en/latest/topics/salt-supported-operating-systems.html>`_
for more information.
* `<https://repo.saltproject.io/>`_
* `Installation Instructions <https://docs.saltproject.io/en/master/topics/installation/index.html>`_
To download and install Salt, see:
* `The Salt install guide <https://docs.saltproject.io/salt/install-guide/en/latest/index.html>`_
* `Salt Project repository <https://repo.saltproject.io/>`_
Salt Project Documentation
Technical support
=================
Report bugs or problems using Salt by opening an issue: `<https://github.com/saltstack/salt/issues>`_
To join our community forum where you can exchange ideas, best practices,
discuss technical support questions, and talk to project maintainers, join our
Slack workspace: `Salt Project Community Slack`_
Salt Project documentation
==========================
Installation instructions, tutorials, in-depth API and module documentation:
Installation instructions, getting started guides, in-depth API
documentation, and contributing to Salt.
* `The Salt install guide <https://docs.saltproject.io/salt/install-guide/en/latest/index.html>`_
* `The Salt user guide <https://docs.saltproject.io/salt/user-guide/en/latest/>`_
* `Latest Salt documentation`_
* `Salt's contributing guide <https://docs.saltproject.io/en/master/topics/development/contributing.html>`_
* `Getting Started with Salt <https://docs.saltproject.io/en/getstarted/>`_
* `Latest Salt Documentation`_
* `Salt’s Contributor Guide <https://docs.saltproject.io/en/master/topics/development/contributing.html>`_
Security Advisories
Security advisories
===================
Keep an eye on the Salt Project
`Security Announcements <https://saltproject.io/security-announcements/>`_
landing page. Salt Project recommends subscribing to the
@ -86,17 +126,26 @@ announcements.
Other channels to receive security announcements include the
`Salt Community mailing list <https://groups.google.com/forum/#!forum/salt-users>`_
and the
`Salt Project Community Slack`_.
and the `Salt Project Community Slack`_.
Responsibly Reporting Security Vulnerabilities
Responsibly reporting security vulnerabilities
++++++++++++++++++++++++++++++++++++++++++++++
When reporting security vulnerabilities for Salt or other SaltStack projects,
refer to the `SECURITY.md`_ file found in this repository.
Engage the Salt Project and The Community
=========================================
Join our community
==================
Salt is built by the Salt Project community, which includes more than 3,000
contributors working in roles just like yours. This well-known and trusted
community works together to improve the underlying technology and extend Salt by
creating a variety of execution and state modules to accomplish the most common
tasks or solve the most important problems that people in your role are likely
to face.
If you want to help extend Salt or solve a problem with Salt, you can join our
community and contribute today.
Please be sure to review our
`Code of Conduct <https://github.com/saltstack/salt/blob/master/CODE_OF_CONDUCT.md>`_.
@ -115,12 +164,12 @@ to the **Salt Project Community Events Calendar** on the main
`<https://saltproject.io>`_ website.
If you have additional questions, email us at saltproject@vmware.com or reach out
directly to the Community Manager, Janae Andrus via Slack. We’d be glad to
directly to the Community Manager, Jimmy Chunga via Slack. We'd be glad to
have you join our community!
License
=======
Salt is licensed under the Apache 2.0 license. Please
see the
`LICENSE file <https://github.com/saltstack/salt/blob/master/LICENSE>`_ for the

11
doc/_incl/requisite_incl.rst
View file

@ -1,9 +1,10 @@
**Before continuing** make sure you have a working Salt installation by
following the :ref:`installation` and the
:ref:`configuration <configuring-salt>` instructions.
following the instructions in the
`Salt install guide <https://docs.saltproject.io/salt/install-guide/en/latest/>`_.
.. admonition:: Stuck?
There are many ways to :ref:`salt-community` including our
`mailing list <https://groups.google.com/forum/#!forum/salt-users>`_
and our `IRC channel <https://web.libera.chat/#salt>`_ #salt.
The Salt Project community can help offer advice and help troubleshoot
technical issues as you're learning about Salt. One of the best places to
talk to the community is on the
`Salt Project Slack workspace <https://saltstackcommunity.slack.com/>`_.

2
doc/contents.rst
View file

@ -10,7 +10,7 @@ Salt Table of Contents
topics/about_salt_project
topics/index
topics/salt_system_architecture
topics/community/index
topics/contributing-guide
topics/installation/index
topics/configuration/index
topics/using_salt

106
doc/topics/community/index.rst
View file

@ -1,106 +0,0 @@
.. _salt-community:
========================
Salt Community Resources
========================
.. rubric:: Join the Salt!
There are many ways to participate in and communicate with the Salt community.
Salt has an active IRC channel and a mailing list.
Mailing List
============
Join the `salt-users mailing list`_. It is the best place to ask questions
about Salt and see whats going on with Salt development! The Salt mailing list
is hosted by Google Groups. It is open to new members.
.. _`salt-users mailing list`: https://groups.google.com/forum/#!forum/salt-users
Additionally, all users of Salt should be subscribed to the Announcements mailing
list which contains important updates about Salt, such as new releases and
security-related announcements. This list is low-traffic.
.. _`salt-announce mailing list`: https://groups.google.com/forum/#!forum/salt-announce
IRC
===
The ``#salt`` IRC channel is hosted on the popular `LiberaChat`_ network. You
can use the `LiberaChat webchat client`_ right from your browser. `Logs of the
IRC channel activity`_ are also available.
.. _LiberaChat: https://libera.chat/
.. _`LiberaChat webchat client`: https://web.libera.chat/#salt
.. _`Logs of the IRC channel activity`: http://ngxbot.nginx.org/logs/%23salt/
If you wish to discuss the development of Salt itself join us in ``#salt-devel``.
Follow on Github
================
The Salt code is developed via Github. Follow Salt for constant updates on what
is happening in Salt development:
|saltrepo|
Long-term planning and strategic decisions are handled via Salt Enhancement Proposals
and can be found on GitHub.
.. _`Salt Enhancement Proposals`: https://github.com/saltstack/salt-enhancement-proposals
Blogs
=====
The Salt Project keeps a `blog`_ with recent news and advancements:
https://saltproject.io/blog/
.. _`blog`: https://saltproject.io/blog/
Example Salt States
===================
The official ``salt-states`` repository is:
https://github.com/saltstack/salt-states
A few examples of salt states from the community:
* https://github.com/blast-hardcheese/blast-salt-states
* https://github.com/kevingranade/kevingranade-salt-state
* https://github.com/uggedal/states
* https://github.com/mattmcclean/salt-openstack/tree/master/salt
* https://github.com/rentalita/ubuntu-setup/
* https://github.com/brutasse/states
* https://github.com/pcrews/salt-data
Follow on ohloh
===============
https://www.ohloh.net/p/salt
Other community links
=====================
- `Salt Project <http://saltproject.io>`_
- `Subreddit <http://www.reddit.com/r/saltstack>`_
- `YouTube <https://www.youtube.com/channel/UCpveTIucFx9ljGelW63-BWg>`_
- `Twitch <https://twitch.tv/saltprojectoss>`_
- `Facebook <https://www.facebook.com/SaltProjectOSS>`_
- `Twitter <https://twitter.com/Salt_Project_OS>`_
- `Wikipedia page <https://en.wikipedia.org/wiki/Salt_(software)>`_
- `Stack Overflow <https://stackoverflow.com/questions/tagged/salt-stack+or+salt-cloud+or+salt-creation>`_
Hack the Source
===============
If you want to get involved with the development of source code or the
documentation efforts, please review the :ref:`contributing documentation
<contributing>`!
.. _`Apache 2.0 license`: http://www.apache.org/licenses/LICENSE-2.0.html

3
doc/topics/contributing-guide.rst Normal file
View file

@ -0,0 +1,3 @@
.. _contributing-import:
.. include:: ../../CONTRIBUTING.rst

297
doc/topics/development/conventions/documentation.rst
View file

@ -1,298 +1,11 @@
.. _salt-docs:
==========================
Writing Salt Documentation
Writing Salt documentation
==========================
Salt's documentation is built using the `Sphinx`_ documentation system. It can
be built in a large variety of output formats including HTML, PDF, ePub, and
manpage.
For the latest information about writing Salt documentation, see:
All the documentation is contained in the main Salt repository. Speaking
broadly, most of the narrative documentation is contained within the
:blob:`doc` subdirectory and most of the reference and API documentation is
written inline with Salt's Python code and extracted using a Sphinx extension.
.. _`Sphinx`: https://www.sphinx-doc.org/en/master/
.. _docs-style:
Style
=====
The Salt project recommends the `IEEE style guide`_ as a general reference for
writing guidelines. Those guidelines are not strictly enforced but rather serve
as an excellent resource for technical writing questions. The `NCBI style
guide`_ is another very approachable resource.
.. _`IEEE style guide`: https://mentor.ieee.org/myproject/Public/mytools/draft/styleman.pdf
.. _`NCBI style guide`: https://www.ncbi.nlm.nih.gov/books/NBK993/
Point-of-view
-------------
Use third-person perspective and avoid "I", "we", "you" forms of address.
Identify the addressee specifically e.g., "users should", "the compiler does",
etc.
Active voice
------------
Use active voice and present-tense. Avoid filler words.
Title capitalization
--------------------
Document titles and section titles within a page should follow normal sentence
capitalization rules. Words that are capitalized as part of a regular sentence
should be capitalized in a title and otherwise left as lowercase. Punctuation
can be omitted unless it aids the intent of the title (e.g., exclamation points
or question marks).
For example:
.. code-block:: restructuredtext
This is a main heading
======================
Paragraph.
This is an exciting sub-heading!
--------------------------------
Paragraph.
.. _docs-modules:
Serial Commas
-------------
According to Wikipedia: In English punctuation, a serial comma or series comma
(also called Oxford comma and Harvard comma) is a comma placed immediately
before the coordinating conjunction (usually "and", "or", or "nor") in a series of
three or more terms. For example, a list of three countries might be punctuated
either as "France, Italy, and Spain" (with the serial comma), or as "France,
Italy and Spain" (without the serial comma)."
When writing a list that includes three or more items, the serial comma should
always be used.
Documenting modules
===================
Documentation for Salt's various module types is inline in the code. During the
documentation build process it is extracted and formatted into the final HTML,
PDF, etc format.
Inline documentation
--------------------
Python has special multi-line strings called docstrings as the first element in
a function or class. These strings allow documentation to live alongside the
code and can contain special formatting. For example:
.. code-block:: python
def my_function(value):
"""
Upper-case the given value
Usage:
.. code-block:: python
val = 'a string'
new_val = myfunction(val)
print(new_val) # 'A STRING'
:param value: a string
:return: a copy of ``value`` that has been upper-cased
"""
return value.upper()
Specify a release for additions or changes
------------------------------------------
New functions or changes to existing functions should include a marker that
denotes what Salt release will be affected. For example:
.. code-block:: python
def my_function(value):
"""
Upper-case the given value
.. versionadded:: 2014.7.0
<...snip...>
"""
return value.upper()
For changes to a function:
.. code-block:: python
def my_function(value, strip=False):
"""
Upper-case the given value
.. versionchanged:: 2016.3.0
Added a flag to also strip whitespace from the string.
<...snip...>
"""
if strip:
return value.upper().strip()
return value.upper()
Adding module documentation to the index
----------------------------------------
Each module type has an index listing all modules of that type. For example:
:ref:`all-salt.modules`, :ref:`all-salt.states`, :ref:`all-salt.renderers`.
New modules must be added to the index manually.
1. Edit the file for the module type:
:blob:`execution modules <doc/ref/modules/all/index.rst>`,
:blob:`state modules<doc/ref/states/all/index.rst>`,
:blob:`renderer modules <doc/ref/renderers/all/index.rst>`, etc.
2. Add the new module to the alphabetized list.
3. :ref:`Build the documentation <docs-building>` which will generate an ``.rst``
file for the new module in the same directory as the ``index.rst``.
4. Commit the changes to ``index.rst`` and the new ``.rst`` file and send a
pull request.
.. _docs-ref:
Cross-references
================
The Sphinx documentation system contains a wide variety of cross-referencing
capabilities.
.. _docs-ref-glossary:
Glossary entries
----------------
Link to :ref:`glossary entries <glossary>` using the `term role`_. A
cross-reference should be added the first time a Salt-specific term is used in
a document.
.. _`term role`: https://www.sphinx-doc.org/en/master/glossary.html#term-role
.. code-block:: restructuredtext
A common way to encapsulate master-side functionality is by writing a
custom :term:`Runner Function`. Custom Runner Functions are easy to write.
.. _docs-ref-index:
Index entries
-------------
Sphinx automatically generates many kinds of index entries, but it is
occasionally useful to manually add items to the index.
One method is to use the `index directive`_ above the document or section that
should appear in the index.
.. _`index directive`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html?highlight=index%20directive#index-generating-markup
.. code-block:: restructuredtext
.. index:: ! Event, event bus, event system
see: Reactor; Event
Another method is to use the `index role`_ inline with the text that should
appear in the index. The index entry is created and the target text is left
otherwise intact.
.. _`index role`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#role-index
.. code-block:: restructuredtext
Information about the :index:`Salt Reactor`
-------------------------------------------
Paragraph.
.. _docs-ref-docs:
Documents and sections
----------------------
Each document should contain a unique top-level label of the form:
.. code-block:: restructuredtext
.. _my-page:
My page
=======
Paragraph.
Unique labels can be linked using the `ref role`_. This allows cross-references
to survive document renames or movement.
.. code-block:: restructuredtext
For more information see :ref:`my-page`.
Note, the ``:doc:`` role should *not* be used to link documents together.
.. _`ref role`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
.. _docs-ref-modules:
Modules
-------
Cross-references to Salt modules can be added using Sphinx's Python domain
roles. For example, to create a link to the :py:func:`test.ping
<salt.modules.test.ping>` function:
.. code-block:: restructuredtext
A useful execution module to test active communication with a minion is the
:py:func:`test.ping <salt.modules.test.ping>` function.
Salt modules can be referenced as well:
.. code-block:: restructuredtext
The :py:mod:`test module <salt.modules.test>` contains many useful
functions for inspecting an active Salt connection.
The same syntax works for all modules types:
.. code-block:: restructuredtext
One of the workhorse state module functions in Salt is the
:py:func:`file.managed <salt.states.file.managed>` function.
.. _docs-ref-settings:
Settings
--------
Individual settings in the Salt Master or Salt Minion configuration files are
cross-referenced using two custom roles, ``conf_master``, and ``conf_minion``.
.. code-block:: restructuredtext
The :conf_minion:`minion ID <id>` setting is a unique identifier for a
single minion.
* `Salt docs contributing guide <https://saltstack.gitlab.io/open/docs/docs-hub/topics/contributing.html>`_
* `Salt rST guide <https://saltstack.gitlab.io/open/docs/docs-hub/topics/rst-guide.html>`_
* `Salt style guide <https://saltstack.gitlab.io/open/docs/docs-hub/topics/style-guide.html>`_

5
doc/topics/tutorials/states_pt4.rst
View file

@ -209,8 +209,9 @@ can be found on GitHub in the `saltstack-formulas`_ collection of repositories.
.. _`saltstack-formulas`: https://github.com/saltstack-formulas
If you have any questions, suggestions, or just want to chat with other people
who are using Salt, we have a very :ref:`active community <salt-community>`
and we'd love to hear from you.
who are using Salt, we have a very active community and we'd love to hear from
you. One of the best places to talk to the community is on the
`Salt Project Slack workspace <https://saltstackcommunity.slack.com/>`_.
In addition, by continuing to the :ref:`Orchestrate Runner <orchestrate-runner>` docs,
you can learn about the powerful orchestration of which Salt is capable.