Contributing

All contributions to ruyaml are welcome. Please post an issue or, if possible, a pull request (PR) on github.

Please don’t use issues to post support questions.

TODO:: The maintainers of ruyaml don’t have an official support channel yet.

Documentation

The documentation for ruyaml is written in the ReStructured Text format and follows the Sphinx Document Generator’s conventions.

Code

Code changes are welcome as well, but anything beyond a minor change should be tested (tox/pytest), checked for typing conformance (mypy) and pass pep8 conformance (flake8).

In my experience it is best to use two virtualenv environments, one with the latest Python from the 2.7 series, the other with 3.5 or 3.6. In the site-packages directory of each virtualenv make a soft link to the ruyaml directory of your (cloned and checked out) copy of the repository. Do not under any circumstances run pip install -e . or python setup.py -e . it will not work (at least not until these commands are fixed to support packages with namespaces).

You can install tox, pytest, mypy and flake8 in the Python3 virtualenv, or in a virtualenv of their own. If all of these commands pass without warning/error, you can create your pull-request.

Flake

The Flake8 configuration is part of setup.py:

[flake8]
show-source = True
max-line-length = 95
ignore = F405

The suppress of F405 is necessary to allow from xxx import *.

Please make sure your checked out source passes flake8 without test (it should). Then make your changes pass without any warnings/errors.

Tox/pytest

Whether you add something or fix some bug with your code changes, first add one or more tests that fail in the unmodified source when running tox. Once that is in place add your code, which should have as a result that your added test(s) no longer fail, and neither should any other existing tests.

Typing/mypy

You should run mypy from ruyaml’s source directory:

mypy --strict --follow-imports silent lib/ruyaml/*.py

This command should give no errors or warnings.

Vulnerabilities

If you find a vulnerability in ruyaml (e.g. that would show the safe and rt loader are not safe due to a bug in the software)), please contact the maintainers directly via email.

After the vulnerability is removed, and affected parties notified to allow them to update versions, the vulnerability will be published, and your role in finding/resolving this properly attributed.