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
135
136
137
138
139
|
version: 0.2
text: smd
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.
|
