version: 0.1
output: rst
fix_inline_single_backquotes: true
pdf: true
--- |
************
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 bitbucket.

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

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

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 reStructuredText mixed with Python, each in separate YAML documents
within a single file. If you know a bit of YAML, Python and reStructuredText it
will be clear how that works.

If you want to contribute to the documentation, you can sent 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 Bitbucket, 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 you
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 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 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
Bitbucket and pushing to PyPI, with nuances coming from the ``_package_data``
information in ``__init__.py``. Including 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 made 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 of 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 notified to allow them
to update versions, the vulnerability will be published, and your role in
finding/resolving this properly attributed.