Contributing¶

Any contribution to ruamel.yaml is welcome, be it in the form of an email, a question on stackoverflow (I\'ll get notified of that when you tag it with ruamel.yaml), an issue or pull-request (PR) on sourceforge.

Contributing via stackoverflow is, for most, easy to do. When I answer your question there and the answer warrants an extension to the documentation or code, I will include it in a documentation update and/or future (normally the next) release of ruamel.yaml.

Please don\'t post support questions as an issue on sourceforge.

Documentation¶

The documentation for ruamel.yaml is in YAML, more specifically in ryd ( /rɑɪt/, pronounced like the verb "write" ). This is Markdown (previously reStructuredText) mixed with Python, each in separate YAML documents within a single file. If you know a bit of YAML, Python and Markdown, it will be clear how that works.

If you want to contribute to the documentation, you can send me a clear description of the needed changes, e.g. as a unified diff. If the changes encompass multiple documents in a .ryd file, it is best to install ryd (use a virtualenv!), clone the ruamel.yaml repository on sourceforge, edit documentation, run ryd:

ryd --pdf '**/*.ryd'

(quoting might not be necessary depending on your shell), and once the PDF(s) look acceptable, submit a pull-request.

ryd will check your file for single backquotes (my most common mistake going back and forth between reStructuredText and other mark up).

If you contribute example programs, note that ryd will automatically run your program (so it should be correct) and can include the output of the program in the resulting .rst (and PDF) file.

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 version currently supported, the other with the oldest supported version. In the site-packages directory of each virtualenv make a soft link to the ruamel 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¶

My ~/.config/flake8 file:

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

The suppress of F405 is necessary to allow from xxx import *, which I have not removed in all places (yet).

First 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¶

If you add methods or functions to ruamel.yaml, you will need to add Python 2.7 compatible typing information in order for mypy to pass without error.

I run mypy from the directory where the (link to) ruamel directory is using:

mypy --py2 --strict --follow-imports silent ruamel/yaml/*.py

This should give no errors or warnings

Generated files¶

I use a minimal environment when developing, void of most artifacts needed for packaging, testing etc. These artifact files are generated, just before committing to sourceforge and pushing to PyPI, with nuances coming from the _package_data information in __init__.py. Included changes in these files will automatically be reverted, even assuming your PR is accepted as is.

Consider the following files read-only (if you think changes need to be made to these, contact me):

setup.py
tox.ini
LICENSE
_ryd/conf.py
-ryd/Makefile

Vulnerabilities¶

If you find a vulnerability in ruamel.yaml (e.g. that would show the safe and rt loader are not safe due to a bug in the software)), please contact me directly via email, or by leaving a comment on StackOverflow (below any of my posts), without going into the details about the vulnerability. After contact is estabilished I will work to eliminate the vulnerability in a timely fashion. After the vulnerability is removed, and affected parties haven been notified to allow them to update versions, the vulnerability will be published, and your role in finding/resolving this properly attributed.

Please note that there is a CVE out there against ruamel.yaml, that states that the input of the function load() is not checked. As the use of ruamel.yaml.load() was never the default, was documented to potentially cause problems when specific parameters were provided, and issued a warning, this was always an inappropriate statement. (To compare: no such CVE was given for the use of the Python standard library function pickle.load, which only documents which is default function to use and only documented to potentially dangerious). The whole CVE is moot, with the removal of the load() function 0.18.