1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
version: 0.2
text: 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 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 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 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 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
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.
|
