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