version: 0.2
text: md
pdf: false
--- |
# 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](https://pypi.python.org/pypi/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.