mirror of
https://github.com/saltstack/salt.git
synced 2025-04-17 10:10:20 +00:00
Cleanup contributing guides; main in repo root
This commit is contained in:
ScriptAutomate
Megan Wilhite
parent
9cf4600f61
commit
497d0df402
6 changed files with 608 additions and 810 deletions
88
.github/CONTRIBUTING.md
vendored
88
.github/CONTRIBUTING.md
vendored
|
|
@ -1,88 +0,0 @@
|
||||||
License Notice
|
|
||||||
==============
|
|
||||||
|
|
||||||
The Salt project is open and encouraging to code contributions. Please be
|
|
||||||
advised that all code contributions will be licensed under the Apache 2.0
|
|
||||||
License. We cannot accept contributions that already hold a License other
|
|
||||||
than Apache 2.0 without explicit exception.
|
|
||||||
|
|
||||||
|
|
||||||
Reporting Issues
|
|
||||||
================
|
|
||||||
|
|
||||||
The Salt issue tracker is used for feature requests and bug reports.
|
|
||||||
|
|
||||||
Bugs
|
|
||||||
----
|
|
||||||
|
|
||||||
A bug is a *demonstrable problem* that is caused by the code in the repository.
|
|
||||||
|
|
||||||
Please read the following guidelines before you
|
|
||||||
[report an issue](https://github.com/saltstack/salt/issues).
|
|
||||||
|
|
||||||
1. **Use the GitHub issue search** -- check if the issue has
|
|
||||||
already been reported. If it has been, please comment on the existing issue.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — Various point-release branches, such
|
|
||||||
as ``2016.3``, ``2016.11``, or even ``develop``, may already contain
|
|
||||||
a fix. Please try to reproduce the bug against the latest git ``HEAD`` or
|
|
||||||
the latest release.
|
|
||||||
|
|
||||||
3. **Isolate the demonstrable problem** -- make sure that the
|
|
||||||
code in the project's repository is *definitely* responsible for the issue.
|
|
||||||
|
|
||||||
4. **Include a reproducible example** -- Provide the steps which
|
|
||||||
led you to the problem.
|
|
||||||
|
|
||||||
Please try to be as detailed as possible in your report, too. What is your
|
|
||||||
environment? What steps will reproduce the issue? What Operating System? What
|
|
||||||
would you expect to be the outcome? All these details will help people to
|
|
||||||
assess and fix any potential bugs.
|
|
||||||
|
|
||||||
**Including the output of** ``salt --versions-report`` **will always help.**
|
|
||||||
|
|
||||||
Valid bugs will be categorized for the next release and worked on as quickly
|
|
||||||
as resources can be reasonably allocated.
|
|
||||||
|
|
||||||
Features
|
|
||||||
--------
|
|
||||||
|
|
||||||
Salt is always working to be more powerful. Feature additions and requests are
|
|
||||||
welcomed. When requesting a feature it will be categorized for a release or
|
|
||||||
placed under the "Feature" label.
|
|
||||||
|
|
||||||
If a new feature is desired, the fastest way to get it into Salt is to
|
|
||||||
contribute the code. Before starting on a new feature, an issue should be filed
|
|
||||||
for it. The one requesting the feature will be able to then discuss the feature
|
|
||||||
with the Salt team and discover the best way to get the feature into Salt and
|
|
||||||
if the feature makes sense.
|
|
||||||
|
|
||||||
It is extremely common that the desired feature has already been completed.
|
|
||||||
Look for it in the docs, ask about it first in IRC, and on the mailing list
|
|
||||||
before filing the request. It is also common that the problem which would be
|
|
||||||
solved by the new feature can be easily solved another way, which is a great
|
|
||||||
reason to ask first.
|
|
||||||
|
|
||||||
Fixing issues
|
|
||||||
=============
|
|
||||||
|
|
||||||
If you wish to help us fix the issue you're reporting,
|
|
||||||
[Salt's documentation](http://docs.saltstack.com/en/master/index.html)
|
|
||||||
already includes information to help you setup a development environment,
|
|
||||||
under [Developing Salt](http://docs.saltstack.com/en/master/topics/development/hacking.html).
|
|
||||||
|
|
||||||
[SaltStack's Contributing documentation](https://docs.saltstack.com/en/master/topics/development/contributing.html)
|
|
||||||
is also helpful, as it explains sending in pull requests, keeping your
|
|
||||||
salt branches in sync, and knowing
|
|
||||||
[which branch](https://docs.saltstack.com/en/master/topics/development/contributing.html#which-salt-branch)
|
|
||||||
new features or bug fixes should be submitted against.
|
|
||||||
|
|
||||||
Fix the issue you have in hand and, if possible, also add a test case to Salt's
|
|
||||||
testing suite. Then, create a
|
|
||||||
[pull request](http://docs.saltstack.com/en/master/topics/development/contributing.html#sending-a-github-pull-request),
|
|
||||||
and **that's it**!
|
|
||||||
|
|
||||||
Salt's development team will review your fix and if everything is OK, your fix
|
|
||||||
will be merged into Salt's code.
|
|
||||||
|
|
||||||
.. vim: set fenc=utf-8 spell spl=en:
|
|
||||||
|
|
@ -1,9 +0,0 @@
|
||||||
# So You Want To Contribute To Salt
|
|
||||||
|
|
||||||
Awesome!
|
|
||||||
|
|
||||||
Check out our contributing guide in
|
|
||||||
[doc/topics/development/contributing.rst][1]
|
|
||||||
|
|
||||||
|
|
||||||
[1]: https://docs.saltstack.com/en/latest/topics/development/contributing.html
|
|
||||||
606
CONTRIBUTING.rst
Normal file
606
CONTRIBUTING.rst
Normal file
|
|
@ -0,0 +1,606 @@
|
||||||
|
============
|
||||||
|
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://webchat.freenode.net/#salt>`__,
|
||||||
|
the `community Slack <https://saltstackcommunity.herokuapp.com/>`__,
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
end out with a functioning dev environment and be able to submit your
|
||||||
|
first PR.
|
||||||
|
|
||||||
|
This guide assumes at least a passing familiarity with
|
||||||
|
`Git <https://git-scm.com/>`__, a common version control tool used
|
||||||
|
across many open source projects, and is necessary for contributing to
|
||||||
|
Salt. For an introduction to Git, watch `Salt Docs Clinic - Git For the
|
||||||
|
True
|
||||||
|
Beginner <https://www.youtube.com/watch?v=zJw6KNvmuq4&ab_channel=SaltStack>`__.
|
||||||
|
Because of its widespread use, there are many resources for learning
|
||||||
|
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
|
||||||
|
----------------------------------------
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
|
||||||
|
export PATH="$HOME/.pyenv/bin:$PATH"
|
||||||
|
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
|
||||||
|
|
||||||
|
On Mac
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
|
Install pyenv using brew:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
brew update
|
||||||
|
brew install pyenv
|
||||||
|
brew install pyenv-virtualenv
|
||||||
|
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Now add pyenv to your ``.bashrc``:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
|
||||||
|
pyenv init 2>> ~/.bashrc
|
||||||
|
pyenv virtualenv-init 2>> ~/.bashrc
|
||||||
|
|
||||||
|
For other shells, see `the pyenv
|
||||||
|
instructions <https://github.com/pyenv/pyenv#basic-github-checkout>`__.
|
||||||
|
|
||||||
|
Go ahead and restart your shell. Now you should be able to install a new
|
||||||
|
version of Python:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pyenv install 3.7.0
|
||||||
|
|
||||||
|
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
|
||||||
|
new virtual environment with this command:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pyenv virtualenv 3.7.0 salt
|
||||||
|
|
||||||
|
Then activate it:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
pyenv activate salt
|
||||||
|
|
||||||
|
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!
|
||||||
|
~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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/>`__
|
||||||
|
for how to implement it. But if you just want to hurry and get started
|
||||||
|
you can go ahead and follow these steps:
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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.
|
||||||
|
|
||||||
|
.. 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
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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
|
||||||
|
the chance that your merge request will get reviewed and merged. Nox
|
||||||
|
enables us to run multiple different test configurations, as well as
|
||||||
|
other common tasks. You can think of it as Make with superpowers.
|
||||||
|
Pre-commit does what it sounds like: it configures some Git pre-commit
|
||||||
|
hooks to run ``black`` for formatting, ``isort`` for keeping our imports
|
||||||
|
sorted, and ``pylint`` to catch issues like unused imports, among
|
||||||
|
others. You can easily install them in your virtualenv with:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
python -m pip install pre-commit nox
|
||||||
|
pre-commit install
|
||||||
|
|
||||||
|
.. 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.
|
||||||
|
|
||||||
|
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
|
||||||
|
start hacking on Salt!
|
||||||
|
|
||||||
|
Salt Issues
|
||||||
|
-----------
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
tracker on
|
||||||
|
GitHub <https://github.com/saltstack/salt/issues/new/choose>`__.
|
||||||
|
|
||||||
|
Creating a **good** report can take a little bit of time - but every
|
||||||
|
minute you invest in making it easier for others to reproduce and
|
||||||
|
understand your issue is time well spent. The faster someone can
|
||||||
|
understand your issue, the faster it will be able to get fixed
|
||||||
|
correctly.
|
||||||
|
|
||||||
|
The thing that every issue needs goes by many names, but one at least as
|
||||||
|
good as any other is MCVE - **M**\ inimum **C**\ omplete
|
||||||
|
**V**\ erifiable **E**\ xample.
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
MCVE eliminates back and forth required to reproduce/verify the issue so
|
||||||
|
someone can actually create a fix.
|
||||||
|
|
||||||
|
Pick An Issue
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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>`__
|
||||||
|
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,
|
||||||
|
just leaving some information about when you expect to pick things up
|
||||||
|
again is a great idea!
|
||||||
|
|
||||||
|
Hacking Away
|
||||||
|
------------
|
||||||
|
|
||||||
|
Salt, Tests, Documentation, and You
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Before approving code contributions, Salt requires:
|
||||||
|
|
||||||
|
- documentation
|
||||||
|
- meaningful passing tests
|
||||||
|
- correct code
|
||||||
|
|
||||||
|
Documentation fixes just require correct documentation.
|
||||||
|
|
||||||
|
What If I Don’t Write Tests or Docs?
|
||||||
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
|
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>`__.
|
||||||
|
We also regularly stream our test clinic `live on
|
||||||
|
Twitch <https://www.twitch.tv/saltstackinc>`__ every Tuesday afternoon
|
||||||
|
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. Since we use nox, you can
|
||||||
|
build your docs and view them in your browser 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
|
||||||
|
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
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
want to write some tests and code.
|
||||||
|
|
||||||
|
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
|
||||||
|
able to run Salt locally. The first thing you need to do is install Salt
|
||||||
|
as an editable pip install:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
python -m pip install -e .
|
||||||
|
|
||||||
|
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
|
||||||
|
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
|
||||||
|
``local/`` directory, so we can put all of our personal files there.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
mkdir -p local/etc/salt/
|
||||||
|
|
||||||
|
Create a master config file as ``local/etc/salt/master``:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
cat <<EOF >local/etc/salt/master
|
||||||
|
user: $(whoami)
|
||||||
|
root_dir: $PWD/local/
|
||||||
|
publish_port: 55505
|
||||||
|
ret_port: 55506
|
||||||
|
EOF
|
||||||
|
|
||||||
|
And a minion config as ``local/etc/salt/minion``:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
cat <<EOF >local/etc/salt/minion
|
||||||
|
user: $(whoami)
|
||||||
|
root_dir: $PWD/local/
|
||||||
|
master: localhost
|
||||||
|
id: saltdev
|
||||||
|
master_port: 55506
|
||||||
|
EOF
|
||||||
|
|
||||||
|
Now you can start your Salt master and minion, specifying the config
|
||||||
|
dir.
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
salt-master --config-dir=local/etc/salt/ --log-level=debug --daemon
|
||||||
|
salt-minion --config-dir=local/etc/salt/ --log-level=debug --daemon
|
||||||
|
|
||||||
|
Now you should be able to accept the minion key:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
salt-key -c local/etc/salt -Ay
|
||||||
|
|
||||||
|
And check that your master/minion are communicating:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
salt -c local/etc/salt \* test.version
|
||||||
|
|
||||||
|
Rather than running ``test.version`` from your master, you can run it
|
||||||
|
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
|
||||||
|
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!
|
||||||
|
|
||||||
|
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
|
||||||
|
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!
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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
|
||||||
|
find those in the ``salt/tests`` directory.
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
- What, specifically, failed?
|
||||||
|
- 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
|
||||||
|
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.
|
||||||
|
|
||||||
|
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
|
||||||
|
tests. You should have it installed by this point but if not you can
|
||||||
|
install it with this:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
python -m pip install nox
|
||||||
|
|
||||||
|
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
|
||||||
|
`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
|
||||||
|
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.
|
||||||
|
|
||||||
|
Changelog and Commit!
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
When you write your commit message you should use imperative style. Do
|
||||||
|
this:
|
||||||
|
|
||||||
|
Add frobnosticate capability
|
||||||
|
|
||||||
|
Don’t do this:
|
||||||
|
|
||||||
|
Added frobnosticate capability
|
||||||
|
|
||||||
|
But that advice is backwards for the changelog. We follow the
|
||||||
|
`keepachangelog <https://keepachangelog.com/en/1.0.0/>`__ approach for
|
||||||
|
our changelog, and use towncrier to generate it for each release. As a
|
||||||
|
contributor, all that means is that you need to add a file to the
|
||||||
|
``salt/changelog`` directory, using the ``<issue #>.<type>`` format. For
|
||||||
|
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
|
||||||
|
|
||||||
|
- 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?
|
||||||
|
|
||||||
|
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
|
||||||
|
out our `PR
|
||||||
|
guidelines <https://docs.saltproject.io/en/develop/topics/development/pull_requests.html>`__.
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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://webchat.freenode.net/#salt>`__, or Community
|
||||||
|
Slack.
|
||||||
|
|
||||||
|
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 -
|
||||||
|
perhaps you encountered the rare case where your PR has a much larger
|
||||||
|
scope than initially assumed.
|
||||||
|
|
||||||
|
Whatever the case, simply make the requested changes (or discuss why the
|
||||||
|
requests are incorrect), and push up your new commits. If your PR is
|
||||||
|
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
|
||||||
|
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
|
||||||
|
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
|
||||||
|
developer! You rock!
|
||||||
|
|
||||||
|
Troubleshooting
|
||||||
|
---------------
|
||||||
|
|
||||||
|
zmq.core.error.ZMQError
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
Once the minion starts, you may see an error like the following::
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
zmq.core.error.ZMQError: ipc path "/path/to/your/virtualenv/var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc" is longer than 107 characters (sizeof(sockaddr_un.sun_path)).
|
||||||
|
|
||||||
|
This means that the path to the socket the minion is using is too long.
|
||||||
|
This is a system limitation, so the only workaround is to reduce the
|
||||||
|
length of this path. This can be done in a couple different ways:
|
||||||
|
|
||||||
|
1. Create your virtualenv in a path that is short enough.
|
||||||
|
2. Edit the :conf_minion:``sock_dir`` minion config variable and reduce
|
||||||
|
its length. Remember that this path is relative to the value you set
|
||||||
|
in :conf_minion:``root_dir``.
|
||||||
|
|
||||||
|
NOTE: The socket path is limited to 107 characters on Solaris and Linux,
|
||||||
|
and 103 characters on BSD-based systems.
|
||||||
|
|
||||||
|
No permissions to access …
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
If you forget to pass your config path to any of the ``salt*`` commands,
|
||||||
|
you might see
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
No permissions to access "/var/log/salt/master", are you running as the
|
||||||
|
correct user?
|
||||||
|
|
||||||
|
Just pass ``-c local/etc/salt`` (or whatever you named it)
|
||||||
|
|
||||||
|
File descriptor limit
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
You might need to raise your file descriptor limit. You can check it
|
||||||
|
with:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
ulimit -n
|
||||||
|
|
||||||
|
If the value is less than 3072, you should increase it with:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
ulimit -n 3072
|
||||||
|
# For c-shell:
|
||||||
|
limit descriptors 3072
|
||||||
|
|
||||||
|
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
|
||||||
|
this:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
nox > Re-using existing virtual environment at .nox/pytest-parametrized-3-crypto-none-transport-zeromq-coverage-false.
|
||||||
|
|
||||||
|
For this, you would be able to install with:
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
.nox/pytest-parametrized-3-crypto-none-transport-zeromq-coverage-false/bin/python -m pip install pygit2
|
||||||
|
|
@ -1,6 +1,6 @@
|
||||||
include AUTHORS
|
include AUTHORS
|
||||||
include CODE_OF_CONDUCT.md
|
include CODE_OF_CONDUCT.md
|
||||||
include CONTRIBUTING.md
|
include CONTRIBUTING.rst
|
||||||
include LICENSE
|
include LICENSE
|
||||||
include NOTICE
|
include NOTICE
|
||||||
include README.rst
|
include README.rst
|
||||||
|
|
|
||||||
|
|
@ -1,106 +0,0 @@
|
||||||
#!/usr/bin/env python
|
|
||||||
# -*- coding: utf-8 -*-
|
|
||||||
"""
|
|
||||||
:codeauthor: Pedro Algarvio (pedro@algarvio.me)
|
|
||||||
|
|
||||||
|
|
||||||
setup-transifex-config
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Setup the Transifex client configuration file
|
|
||||||
"""
|
|
||||||
|
|
||||||
import getpass
|
|
||||||
|
|
||||||
# Import python libs
|
|
||||||
import os
|
|
||||||
import sys
|
|
||||||
|
|
||||||
import ConfigParser
|
|
||||||
|
|
||||||
HOST = "https://www.transifex.com"
|
|
||||||
RCFILE = os.path.abspath(
|
|
||||||
os.environ.get("TRANSIFEX_RC", os.path.expanduser("~/.transifexrc"))
|
|
||||||
)
|
|
||||||
|
|
||||||
|
|
||||||
def main():
|
|
||||||
"""
|
|
||||||
Run the setup code
|
|
||||||
"""
|
|
||||||
print(
|
|
||||||
"This script will setup a Transifex client configuration file, or, "
|
|
||||||
"if it already exists, make some minimal checks to see if it's "
|
|
||||||
"properly configured\n"
|
|
||||||
)
|
|
||||||
if not os.path.exists(RCFILE):
|
|
||||||
while True:
|
|
||||||
username = os.environ.get("TRANSIFEX_USER", None)
|
|
||||||
if username is not None:
|
|
||||||
break
|
|
||||||
try:
|
|
||||||
username = raw_input("What is your username on Transifex.com? ")
|
|
||||||
if username:
|
|
||||||
break
|
|
||||||
except KeyboardInterrupt:
|
|
||||||
print
|
|
||||||
sys.exit(1)
|
|
||||||
while True:
|
|
||||||
password = os.environ.get("TRANSIFEX_PASS", None)
|
|
||||||
if password is not None:
|
|
||||||
break
|
|
||||||
try:
|
|
||||||
password = getpass.getpass("What is your password on Transifex.com? ")
|
|
||||||
if password:
|
|
||||||
break
|
|
||||||
except KeyboardInterrupt:
|
|
||||||
print
|
|
||||||
sys.exit(1)
|
|
||||||
|
|
||||||
config = ConfigParser.SafeConfigParser()
|
|
||||||
config.add_section(HOST)
|
|
||||||
config.set(HOST, "token", "")
|
|
||||||
config.set(HOST, "hostname", HOST)
|
|
||||||
config.set(HOST, "username", username)
|
|
||||||
config.set(HOST, "password", password)
|
|
||||||
|
|
||||||
config.write(open(RCFILE, "w"))
|
|
||||||
print("username and password stored in '{0}'".format(RCFILE))
|
|
||||||
|
|
||||||
os.chmod(RCFILE, 0600)
|
|
||||||
print("Secured the permissions on '{0}' to 0600".format(RCFILE))
|
|
||||||
|
|
||||||
sys.exit(0)
|
|
||||||
|
|
||||||
# The file exists, let's see if it's properly configured
|
|
||||||
config = ConfigParser.SafeConfigParser()
|
|
||||||
config.read([RCFILE])
|
|
||||||
|
|
||||||
if not config.has_section(HOST):
|
|
||||||
print(
|
|
||||||
"'~/.transifexrc' is not properly configured, it's missing "
|
|
||||||
"the {0} section".format(HOST)
|
|
||||||
)
|
|
||||||
|
|
||||||
for setting in ("username", "password", "hostname", "token"):
|
|
||||||
if not config.has_option(HOST, setting):
|
|
||||||
print(
|
|
||||||
"'~/.transifexrc' is not properly configured, it's "
|
|
||||||
"missing the {0} option".format(setting)
|
|
||||||
)
|
|
||||||
sys.exit(1)
|
|
||||||
|
|
||||||
if setting == "token":
|
|
||||||
# Token should be left empty
|
|
||||||
continue
|
|
||||||
|
|
||||||
if not config.get(HOST, setting):
|
|
||||||
print(
|
|
||||||
"'~/.transifexrc' is not properly configured, it's "
|
|
||||||
"missing a value for the {0} option".format(setting)
|
|
||||||
)
|
|
||||||
sys.exit(1)
|
|
||||||
|
|
||||||
|
|
||||||
if __name__ == "__main__":
|
|
||||||
main()
|
|
||||||
|
|
@ -1,608 +1,3 @@
|
||||||
.. _contributing:
|
.. _contributing:
|
||||||
|
|
||||||
============
|
.. include:: ../../../CONTRIBUTING.rst
|
||||||
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://webchat.freenode.net/#salt>`__,
|
|
||||||
the `community Slack <https://saltstackcommunity.herokuapp.com/>`__,
|
|
||||||
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.saltstack.com/en/latest/topics/development/conventions/documentation.html#salt-docs>`__.
|
|
||||||
- Providing workarounds, patches, or other code without tests.
|
|
||||||
- Telling 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
|
|
||||||
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
|
|
||||||
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
|
|
||||||
end out with a functioning dev environment and be able to submit your
|
|
||||||
first PR.
|
|
||||||
|
|
||||||
This guide assumes at least a passing familiarity with
|
|
||||||
`Git <https://git-scm.com/>`__, a common version control tool used
|
|
||||||
across many open source projects, and is necessary for contributing to
|
|
||||||
Salt. For an introduction to Git, watch `Salt Docs Clinic - Git For the
|
|
||||||
True
|
|
||||||
Beginner <https://www.youtube.com/watch?v=zJw6KNvmuq4&ab_channel=SaltStack>`__.
|
|
||||||
Because of its widespread use, there are many resources for learning
|
|
||||||
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
|
|
||||||
----------------------------------------
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
|
|
||||||
export PATH="$HOME/.pyenv/bin:$PATH"
|
|
||||||
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
|
|
||||||
|
|
||||||
On Mac
|
|
||||||
~~~~~~
|
|
||||||
|
|
||||||
Install pyenv using brew:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
brew update
|
|
||||||
brew install pyenv
|
|
||||||
brew install pyenv-virtualenv
|
|
||||||
|
|
||||||
--------------
|
|
||||||
|
|
||||||
Now add pyenv to your ``.bashrc``:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
echo 'export PATH="$HOME/.pyenv/bin:$PATH"' >> ~/.bashrc
|
|
||||||
pyenv init 2>> ~/.bashrc
|
|
||||||
pyenv virtualenv-init 2>> ~/.bashrc
|
|
||||||
|
|
||||||
For other shells, see `the pyenv
|
|
||||||
instructions <https://github.com/pyenv/pyenv#basic-github-checkout>`__.
|
|
||||||
|
|
||||||
Go ahead and restart your shell. Now you should be able to install a new
|
|
||||||
version of Python:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pyenv install 3.7.0
|
|
||||||
|
|
||||||
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
|
|
||||||
new virtual environment with this command:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pyenv virtualenv 3.7.0 salt
|
|
||||||
|
|
||||||
Then activate it:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
pyenv activate salt
|
|
||||||
|
|
||||||
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!
|
|
||||||
~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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/>`__
|
|
||||||
for how to implement it. But if you just want to hurry and get started
|
|
||||||
you can go ahead and follow these steps:
|
|
||||||
|
|
||||||
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
|
|
||||||
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
|
|
||||||
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
|
|
||||||
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.
|
|
||||||
|
|
||||||
.. 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
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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
|
|
||||||
the chance that your merge request will get reviewed and merged. Nox
|
|
||||||
enables us to run multiple different test configurations, as well as
|
|
||||||
other common tasks. You can think of it as Make with superpowers.
|
|
||||||
Pre-commit does what it sounds like: it configures some Git pre-commit
|
|
||||||
hooks to run ``black`` for formatting, ``isort`` for keeping our imports
|
|
||||||
sorted, and ``pylint`` to catch issues like unused imports, among
|
|
||||||
others. You can easily install them in your virtualenv with:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
python -m pip install pre-commit nox
|
|
||||||
pre-commit install
|
|
||||||
|
|
||||||
.. 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.
|
|
||||||
|
|
||||||
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
|
|
||||||
start hacking on Salt!
|
|
||||||
|
|
||||||
Salt Issues
|
|
||||||
-----------
|
|
||||||
|
|
||||||
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
|
|
||||||
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
|
|
||||||
tracker on
|
|
||||||
GitHub <https://github.com/saltstack/salt/issues/new/choose>`__.
|
|
||||||
|
|
||||||
Creating a **good** report can take a little bit of time - but every
|
|
||||||
minute you invest in making it easier for others to reproduce and
|
|
||||||
understand your issue is time well spent. The faster someone can
|
|
||||||
understand your issue, the faster it will be able to get fixed
|
|
||||||
correctly.
|
|
||||||
|
|
||||||
The thing that every issue needs goes by many names, but one at least as
|
|
||||||
good as any other is MCVE - **M**\ inimum **C**\ omplete
|
|
||||||
**V**\ erifiable **E**\ xample.
|
|
||||||
|
|
||||||
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
|
|
||||||
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
|
|
||||||
MCVE eliminates back and forth required to reproduce/verify the issue so
|
|
||||||
someone can actually create a fix.
|
|
||||||
|
|
||||||
Pick An Issue
|
|
||||||
~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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>`__
|
|
||||||
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,
|
|
||||||
just leaving some information about when you expect to pick things up
|
|
||||||
again is a great idea!
|
|
||||||
|
|
||||||
Hacking Away
|
|
||||||
------------
|
|
||||||
|
|
||||||
Salt, Tests, Documentation, and You
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Before approving code contributions, Salt requires:
|
|
||||||
|
|
||||||
- documentation
|
|
||||||
- meaningful passing tests
|
|
||||||
- correct code
|
|
||||||
|
|
||||||
Documentation fixes just require correct documentation.
|
|
||||||
|
|
||||||
What If I Don’t Write Tests or Docs?
|
|
||||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
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>`__.
|
|
||||||
We also regularly stream our test clinic `live on
|
|
||||||
Twitch <https://www.twitch.tv/saltstackinc>`__ every Tuesday afternoon
|
|
||||||
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. Since we use nox, you can
|
|
||||||
build your docs and view them in your browser 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
|
|
||||||
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
|
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
|
||||||
want to write some tests and code.
|
|
||||||
|
|
||||||
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
|
|
||||||
able to run Salt locally. The first thing you need to do is install Salt
|
|
||||||
as an editable pip install:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
python -m pip install -e .
|
|
||||||
|
|
||||||
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
|
|
||||||
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
|
|
||||||
``local/`` directory, so we can put all of our personal files there.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
mkdir -p local/etc/salt/
|
|
||||||
|
|
||||||
Create a master config file as ``local/etc/salt/master``:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
cat <<EOF >local/etc/salt/master
|
|
||||||
user: $(whoami)
|
|
||||||
root_dir: $PWD/local/
|
|
||||||
publish_port: 55505
|
|
||||||
ret_port: 55506
|
|
||||||
EOF
|
|
||||||
|
|
||||||
And a minion config as ``local/etc/salt/minion``:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
cat <<EOF >local/etc/salt/minion
|
|
||||||
user: $(whoami)
|
|
||||||
root_dir: $PWD/local/
|
|
||||||
master: localhost
|
|
||||||
id: saltdev
|
|
||||||
master_port: 55506
|
|
||||||
EOF
|
|
||||||
|
|
||||||
Now you can start your Salt master and minion, specifying the config
|
|
||||||
dir.
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
salt-master --config-dir=local/etc/salt/ --log-level=debug --daemon
|
|
||||||
salt-minion --config-dir=local/etc/salt/ --log-level=debug --daemon
|
|
||||||
|
|
||||||
Now you should be able to accept the minion key:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
salt-key -c local/etc/salt -Ay
|
|
||||||
|
|
||||||
And check that your master/minion are communicating:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
salt -c local/etc/salt \* test.version
|
|
||||||
|
|
||||||
Rather than running ``test.version`` from your master, you can run it
|
|
||||||
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
|
|
||||||
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!
|
|
||||||
|
|
||||||
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
|
|
||||||
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!
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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.saltstack.com/en/master/topics/tutorials/writing_tests.html>`__,
|
|
||||||
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
|
|
||||||
keep in mind is, “What, exactly, am I testing?” When a test fails, you
|
|
||||||
should know:
|
|
||||||
|
|
||||||
- What, specifically, failed?
|
|
||||||
- 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
|
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
|
||||||
tests. You should have it installed by this point but if not you can
|
|
||||||
install it with this:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
python -m pip install nox
|
|
||||||
|
|
||||||
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
|
|
||||||
`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
|
|
||||||
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.
|
|
||||||
|
|
||||||
Changelog and Commit!
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
When you write your commit message you should use imperative style. Do
|
|
||||||
this:
|
|
||||||
|
|
||||||
Add frobnosticate capability
|
|
||||||
|
|
||||||
Don’t do this:
|
|
||||||
|
|
||||||
Added frobnosticate capability
|
|
||||||
|
|
||||||
But that advice is backwards for the changelog. We follow the
|
|
||||||
`keepachangelog <https://keepachangelog.com/en/1.0.0/>`__ approach for
|
|
||||||
our changelog, and use towncrier to generate it for each release. As a
|
|
||||||
contributor, all that means is that you need to add a file to the
|
|
||||||
``salt/changelog`` directory, using the ``<issue #>.<type>`` format. For
|
|
||||||
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
|
|
||||||
|
|
||||||
- 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?
|
|
||||||
|
|
||||||
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
|
|
||||||
out our `PR
|
|
||||||
guidelines <https://docs.saltstack.com/en/develop/topics/development/pull_requests.html>`__.
|
|
||||||
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
|
|
||||||
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
|
|
||||||
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://webchat.freenode.net/#salt>`__, or Community
|
|
||||||
Slack.
|
|
||||||
|
|
||||||
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 -
|
|
||||||
perhaps you encountered the rare case where your PR has a much larger
|
|
||||||
scope than initially assumed.
|
|
||||||
|
|
||||||
Whatever the case, simply make the requested changes (or discuss why the
|
|
||||||
requests are incorrect), and push up your new commits. If your PR is
|
|
||||||
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
|
|
||||||
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
|
|
||||||
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
|
|
||||||
developer! You rock!
|
|
||||||
|
|
||||||
Troubleshooting
|
|
||||||
---------------
|
|
||||||
|
|
||||||
zmq.core.error.ZMQError
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Once the minion starts, you may see an error like the following::
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
zmq.core.error.ZMQError: ipc path "/path/to/your/virtualenv/var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc" is longer than 107 characters (sizeof(sockaddr_un.sun_path)).
|
|
||||||
|
|
||||||
This means that the path to the socket the minion is using is too long.
|
|
||||||
This is a system limitation, so the only workaround is to reduce the
|
|
||||||
length of this path. This can be done in a couple different ways:
|
|
||||||
|
|
||||||
1. Create your virtualenv in a path that is short enough.
|
|
||||||
2. Edit the :conf_minion:``sock_dir`` minion config variable and reduce
|
|
||||||
its length. Remember that this path is relative to the value you set
|
|
||||||
in :conf_minion:``root_dir``.
|
|
||||||
|
|
||||||
NOTE: The socket path is limited to 107 characters on Solaris and Linux,
|
|
||||||
and 103 characters on BSD-based systems.
|
|
||||||
|
|
||||||
No permissions to access …
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
If you forget to pass your config path to any of the ``salt*`` commands,
|
|
||||||
you might see
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
No permissions to access "/var/log/salt/master", are you running as the
|
|
||||||
correct user?
|
|
||||||
|
|
||||||
Just pass ``-c local/etc/salt`` (or whatever you named it)
|
|
||||||
|
|
||||||
File descriptor limit
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
You might need to raise your file descriptor limit. You can check it
|
|
||||||
with:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
ulimit -n
|
|
||||||
|
|
||||||
If the value is less than 2047, you should increase it with:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
ulimit -n 2047
|
|
||||||
# For c-shell:
|
|
||||||
limit descriptors 2047
|
|
||||||
|
|
||||||
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
|
|
||||||
this:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
nox > Re-using existing virtual environment at .nox/pytest-parametrized-3-crypto-none-transport-zeromq-coverage-false.
|
|
||||||
|
|
||||||
For this, you would be able to install with:
|
|
||||||
|
|
||||||
::
|
|
||||||
|
|
||||||
.nox/pytest-parametrized-3-crypto-none-transport-zeromq-coverage-false/bin/python -m pip install pygit2
|
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue