Skip to content

Commit 02418ce

Browse files
tomschrtomschr
authored
Merge pull request #308 from tomschr/feature/contribution
Add CONTRIBUTING.rst
2 parents e7558a9 + 42bf3e2 commit 02418ce

File tree

2 files changed

+233
-241
lines changed

2 files changed

+233
-241
lines changed

‎CONTRIBUTING.rst‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
.. _contributing:
2+
3+
Contributing to semver
4+
======================
5+
6+
The semver source code is managed using Git and is hosted on GitHub::
7+
8+
git clone git://github.com/python-semver/python-semver
9+
10+
11+
Reporting Bugs and Feedback
12+
---------------------------
13+
14+
If you think you have encountered a bug in semver or have an idea for a new
15+
feature? Great! We like to hear from you.
16+
17+
First, take the time to look into our GitHub `issues`_ tracker if
18+
this already covered. If not, changes are good that we avoid double work.
19+
20+
21+
Prerequisites
22+
-------------
23+
24+
Before you make changes to the code, we would highly appreciate if you
25+
consider the following general requirements:
26+
27+
* Make sure your code adheres to the `Semantic Versioning`_ specification.
28+
29+
* Check if your feature is covered by the Semantic Versioning specification.
30+
If not, ask on its GitHub project https://github.com/semver/semver.
31+
32+
33+
34+
Modifying the Code
35+
------------------
36+
37+
We recommend the following workflow:
38+
39+
#. Fork our project on GitHub using this link:
40+
https://github.com/python-semver/python-semver/fork
41+
42+
#. Clone your forked Git repository (replace ``GITHUB_USER`` with your
43+
account name on GitHub)::
44+
45+
$ git clone git@github.com:GITHUB_USER/python-semver.git
46+
47+
#. Create a new branch. You can name your branch whatever you like, but we
48+
recommend to use some meaningful name. If your fix is based on a
49+
existing GitHub issue, add also the number. Good examples would be:
50+
51+
* ``feature/123-improve-foo`` when implementing a new feature in issue 123
52+
* ``bugfix/234-fix-security-bar`` a bugfixes for issue 234
53+
54+
Use this :command:`git` command::
55+
56+
$ git checkout -b feature/NAME_OF_YOUR_FEATURE
57+
58+
#. Work on your branch and create a pull request:
59+
60+
a. Write test cases and run the complete test suite, see :ref:`testsuite`
61+
for details.
62+
63+
b. Write a changelog entry, see section :ref:`changelog`.
64+
65+
c. If you have implemented a new feature, document it into our
66+
documentation to help our reader. See section :ref:`doc` for
67+
further details.
68+
69+
d. Create a `pull request`_. Describe in the pull request what you did
70+
and why. If you have open questions, ask.
71+
72+
#. Wait for feedback. If you receive any comments, address these.
73+
74+
#. After your pull request got accepted, delete your branch.
75+
76+
77+
.. _testsuite:
78+
79+
Running the Test Suite
80+
----------------------
81+
82+
We use `pytest`_ and `tox`_ to run tests against all supported Python
83+
versions. All test dependencies are resolved automatically.
84+
85+
You can decide to run the complete test suite or only part of it:
86+
87+
* To run all tests, use::
88+
89+
$ tox
90+
91+
If you have not all Python interpreters installed on your system
92+
it will probably give you some errors (``InterpreterNotFound``).
93+
To avoid such errors, use::
94+
95+
$ tox --skip-missing-interpreters
96+
97+
It is possible to use one or more specific Python versions. Use the ``-e``
98+
option and one or more abbreviations (``py36`` for Python 3.6, ``py37`` for
99+
Python 3.7 etc.)::
100+
101+
$ tox -e py36
102+
$ tox -e py36,py37
103+
104+
To get a complete list and a short description, run::
105+
106+
$ tox -av
107+
108+
* To run only a specific test, pytest requires the syntax
109+
``TEST_FILE::TEST_FUNCTION``.
110+
111+
For example, the following line tests only the function
112+
:func:`test_immutable_major` in the file :file:`test_bump.py` for all
113+
Python versions::
114+
115+
$ tox -e py36 -- tests/test_bump.py::test_should_bump_major
116+
117+
By default, pytest prints only a dot for each test function. To
118+
reveal the executed test function, use the following syntax::
119+
120+
$ tox -- -v
121+
122+
You can combine the specific test function with the ``-e`` option, for
123+
example, to limit the tests for Python 3.6 and 3.7 only::
124+
125+
$ tox -e py36,py37 -- tests/test_bump.py::test_should_bump_major
126+
127+
Our code is checked against formatting, style, type, and docstring issues
128+
(`black`_, `flake8`_, `mypy`_, and `docformatter`_).
129+
It is recommended to run your tests in combination with :command:`checks`,
130+
for example::
131+
132+
$ tox -e checks,py36,py37
133+
134+
135+
.. _doc:
136+
137+
Documenting semver
138+
------------------
139+
140+
Documenting the features of semver is very important. It gives our developers
141+
an overview what is possible with semver, how it "feels", and how it is
142+
used efficiently.
143+
144+
.. note::
145+
146+
To build the documentation locally use the following command::
147+
148+
$ tox -e docs
149+
150+
The built documentation is available in :file:`docs/_build/html`.
151+
152+
153+
A new feature is *not* complete if it isn't proberly documented. A good
154+
documentation includes:
155+
156+
* **A docstring**
157+
158+
Each docstring contains a summary line, a linebreak, an optional
159+
directive (see next item), the description of its arguments in
160+
`Sphinx style`_, and an optional doctest.
161+
The docstring is extracted and reused in the :ref:`api` section.
162+
An appropriate docstring should look like this::
163+
164+
def to_tuple(self) -> VersionTuple:
165+
"""
166+
Convert the Version object to a tuple.
167+
168+
.. versionadded:: 2.10.0
169+
Renamed ``VersionInfo._astuple`` to ``VersionInfo.to_tuple`` to
170+
make this function available in the public API.
171+
172+
:return: a tuple with all the parts
173+
174+
>>> semver.Version(5, 3, 1).to_tuple()
175+
(5, 3, 1, None, None)
176+
"""
177+
178+
* **An optional directive**
179+
180+
If you introduce a new feature, change a function/method, or remove something,
181+
it is a good practice to introduce Sphinx directives into the docstring.
182+
This gives the reader an idea what version is affected by this change.
183+
184+
The first required argument, ``VERSION``, defines the version when this change
185+
was introduced. You can choose from:
186+
187+
* ``.. versionadded:: VERSION``
188+
189+
Use this directive to describe a new feature.
190+
191+
* ``.. versionchanged:: VERSION``
192+
193+
Use this directive to describe when something has changed, for example,
194+
new parameters were added, changed side effects, different return values, etc.
195+
196+
* ``.. deprecated:: VERSION``
197+
198+
Use this directive when a feature is deprecated. Describe what should
199+
be used instead, if appropriate.
200+
201+
202+
Add such a directive *after* the summary line, as shown above.
203+
204+
* **The documentation**
205+
206+
A docstring is good, but in most cases it's too dense. API documentation
207+
cannot replace a good user documentation. Describe how
208+
to use your new feature in our documentation. Here you can give your
209+
readers more examples, describe it in a broader context or show
210+
edge cases.
211+
212+
213+
.. _changelog:
214+
215+
Adding a Changelog Entry
216+
------------------------
217+
218+
.. include:: ../changelog.d/README.rst
219+
:start-after: -text-begin-
220+
221+
222+
.. _black: https://black.rtfd.io
223+
.. _docformatter: https://pypi.org/project/docformatter/
224+
.. _flake8: https://flake8.rtfd.io
225+
.. _mypy: http://mypy-lang.org/
226+
.. _issues: https://github.com/python-semver/python-semver/issues
227+
.. _pull request: https://github.com/python-semver/python-semver/pulls
228+
.. _pytest: http://pytest.org/
229+
.. _Semantic Versioning: https://semver.org
230+
.. _Sphinx style: https://sphinx-rtd-tutorial.rtfd.io/en/latest/docstrings.html
231+
.. _tox: https://tox.rtfd.org/
232+

0 commit comments

Comments
 (0)