Skip to content

Navigation Menu

Sign in

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 3d2ad41

Browse filesBrowse files
tomschrtomschr
committed
Prepare for 3.0.0-rc.1 release
* Combine all dev releases together in one changelog * Remove all changelog.d entries and integrate it into CHANGELOG * Move dev releases to file changelog-semver3-devel.rst * Split contributing into different sections * Some doc polishing; use :meth: consistently for semver.Version methods * Fix also some doc bugs * Amend list of contributors and sorted alphabetically by lastname * Correct docstrings on some deprecated functions
1 parent 467ea0c commit 3d2ad41
Copy full SHA for 3d2ad41

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Dismiss banner

52 files changed

+1039
-570
lines changed

‎CHANGELOG.rst

Copy file name to clipboardExpand all lines: CHANGELOG.rst
+140-212Lines changed: 140 additions & 212 deletions
Large diffs are not rendered by default.

‎CONTRIBUTING.rst

Copy file name to clipboardExpand all lines: CONTRIBUTING.rst
+8-186Lines changed: 8 additions & 186 deletions
Original file line numberDiff line numberDiff line change
@@ -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+
1112
Reporting 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

‎CONTRIBUTORS

Copy file name to clipboardExpand all lines: CONTRIBUTORS
+24-17Lines changed: 24 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -22,30 +22,37 @@ Old maintainer:
2222
* Kostiantyn Rybnikov <k-bx@k-bx.com>
2323

2424

25-
Significant contributors
26-
========================
25+
List of Contributors
26+
====================
2727

28-
* Alexander Puzynia <werwolf.by@gmail.com>
29-
* Alexander Shorin <kxepal@gmail.com>
30-
* Anton Talevnin <TalAntR@users.noreply.github.com>
31-
* Ben Finney <ben+python@benfinney.id.au>
28+
(in alphabetical order)
29+
30+
* Jelo Agnasin <jelo@icannhas.com>
3231
* Carles Barrobés <carles@barrobes.com>
33-
* Craig Blaszczyk <masterjakul@gmail.com>
34-
* Damien Nadé <anvil@users.noreply.github.com>
3532
* Eli Bishop <eli-darkly@users.noreply.github.com>
36-
* George Sakkis <gsakkis@users.noreply.github.com>
37-
* Jan Pieter Waagmeester <jieter@jieter.nl>
38-
* Jelo Agnasin <jelo@icannhas.com>
39-
* Karol Werner <karol.werner@ppkt.eu>
4033
* Peter Bittner <django@bittner.it>
41-
* robi-wan <robi-wan@suyu.de>
42-
* sbrudenell <sbrudenell@users.noreply.github.com>
34+
* Craig Blaszczyk <masterjakul@gmail.com>
35+
* Tyler Cross <tyler@crosscollab.com>
36+
* Dennis Felsing <def-@users.noreply.github.com>
37+
* Ben Finney <ben+python@benfinney.id.au>
38+
* Zane Geiger <zanecodes@users.noreply.github.com>
4339
* T. Jameson Little <t.jameson.little@gmail.com>
40+
* Raphael Krupinski <rafalkrupinski@users.noreply.github.com>
4441
* Thomas Laferriere <tlaferriere@users.noreply.github.com>
45-
* Tuure Laurinolli <tuure@laurinolli.net>
46-
* Tyler Cross <tyler@crosscollab.com>
4742
* Zack Lalanne <zack.lalanne@gmail.com>
48-
43+
* Tuure Laurinolli <tuure@laurinolli.net>
44+
* Damien Nadé <anvil@users.noreply.github.com>
45+
* Jan Pieter Waagmeester <jieter@jieter.nl>
46+
* Alexander Puzynia <werwolf.by@gmail.com>
47+
* Lexi Robinson <Lexicality@users.noreply.github.com>
48+
* robi-wan <robi-wan@suyu.de>
49+
* George Sakkis <gsakkis@users.noreply.github.com>
50+
* Mike Salvatore <mssalvatore@users.noreply.github.com>
51+
* sbrudenell <sbrudenell@users.noreply.github.com>
52+
* Alexander Shorin <kxepal@gmail.com>
53+
* Anton Talevnin <TalAntR@users.noreply.github.com>
54+
* Karol Werner <karol.werner@ppkt.eu>
55+
4956
..
5057
Local variables:
5158
coding: utf-8

‎README.rst

Copy file name to clipboardExpand all lines: README.rst
-5Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,3 @@
1-
.. warning::
2-
3-
This is a development version. Do **NOT** use it
4-
in production before the final 3.0.0 is released.
5-
61
Quickstart
72
==========
83

‎changelog.d/284.deprecation.rst

Copy file name to clipboardExpand all lines: changelog.d/284.deprecation.rst
-5Lines changed: 0 additions & 5 deletions
This file was deleted.

‎changelog.d/284.doc.rst

Copy file name to clipboardExpand all lines: changelog.d/284.doc.rst
-1Lines changed: 0 additions & 1 deletion
This file was deleted.

‎changelog.d/284.feature.rst

Copy file name to clipboardExpand all lines: changelog.d/284.feature.rst
-1Lines changed: 0 additions & 1 deletion
This file was deleted.

‎changelog.d/344.bugfix.rst

Copy file name to clipboardExpand all lines: changelog.d/344.bugfix.rst
-5Lines changed: 0 additions & 5 deletions
This file was deleted.

‎changelog.d/388.trivial.rst

Copy file name to clipboardExpand all lines: changelog.d/388.trivial.rst
-3Lines changed: 0 additions & 3 deletions
This file was deleted.

‎changelog.d/pr384.bugfix.rst

Copy file name to clipboardExpand all lines: changelog.d/pr384.bugfix.rst
-11Lines changed: 0 additions & 11 deletions
This file was deleted.

‎changelog.d/pr389.trivial.rst

Copy file name to clipboardExpand all lines: changelog.d/pr389.trivial.rst
-6Lines changed: 0 additions & 6 deletions
This file was deleted.

‎changelog.d/pr392.doc.rst

Copy file name to clipboardExpand all lines: changelog.d/pr392.doc.rst
-1Lines changed: 0 additions & 1 deletion
This file was deleted.

‎changelog.d/pr393.bugfix.rst

Copy file name to clipboardExpand all lines: changelog.d/pr393.bugfix.rst
-1Lines changed: 0 additions & 1 deletion
This file was deleted.

‎changelog.d/pr396.bug.rst

Copy file name to clipboardExpand all lines: changelog.d/pr396.bug.rst
-2Lines changed: 0 additions & 2 deletions
This file was deleted.

‎docs/advanced/convert-pypi-to-semver.rst

Copy file name to clipboardExpand all lines: docs/advanced/convert-pypi-to-semver.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ semver:
135135
def convert2semver(ver: packaging.version.Version) -> semver.Version:
136136
"""Converts a PyPI version into a semver version
137137
138-
:param packaging.version.Version ver: the PyPI version
138+
:param ver: the PyPI version
139139
:return: a semver version
140140
:raises ValueError: if epoch or post parts are used
141141
"""
@@ -145,7 +145,7 @@ semver:
145145
raise ValueError("Can't convert a post part to semver")
146146
147147
pre = None if not ver.pre else "".join([str(i) for i in ver.pre])
148-
semver.Version(*ver.release, prerelease=pre, build=ver.dev)
148+
return semver.Version(*ver.release, prerelease=pre, build=ver.dev)
149149
150150
151151
.. _convert_semver_to_pypi:

‎docs/advanced/create-subclasses-from-version.rst

Copy file name to clipboardExpand all lines: docs/advanced/create-subclasses-from-version.rst
+3-2Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,15 +16,16 @@ but the other behavior is the same, use the following code:
1616

1717

1818
The derived class :class:`SemVerWithVPrefix` can be used like
19-
the original class:
19+
the original class. Additionally, you can pass "incomplete"
20+
version strings like ``v2.3``:
2021

2122
.. code-block:: python
2223
2324
>>> v1 = SemVerWithVPrefix.parse("v1.2.3")
2425
>>> assert str(v1) == "v1.2.3"
2526
>>> print(v1)
2627
v1.2.3
27-
>>> v2 = SemVerWithVPrefix.parse("v2.3.4")
28+
>>> v2 = SemVerWithVPrefix.parse("v2.3")
2829
>>> v2 > v1
2930
True
3031
>>> bad = SemVerWithVPrefix.parse("1.2.4")

‎docs/advanced/index.rst

Copy file name to clipboardExpand all lines: docs/advanced/index.rst
+1Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ Advanced topics
33

44

55
.. toctree::
6+
:maxdepth: 1
67

78
deal-with-invalid-versions
89
create-subclasses-from-version

‎docs/advanced/semverwithvprefix.py

Copy file name to clipboardExpand all lines: docs/advanced/semverwithvprefix.py
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ def parse(cls, version: str) -> "SemVerWithVPrefix":
2020
f"{version!r}: not a valid semantic version tag. "
2121
"Must start with 'v' or 'V'"
2222
)
23-
return super().parse(version[1:])
23+
return super().parse(version[1:], optional_minor_and_patch=True)
2424

2525
def __str__(self) -> str:
2626
# Reconstruct the tag

‎docs/advanced/version-from-file.rst

Copy file name to clipboardExpand all lines: docs/advanced/version-from-file.rst
+5-4Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,17 @@ is to use the following function:
88

99
.. code-block:: python
1010
11+
import os
12+
from typing import Union
1113
from semver.version import Version
1214
13-
def get_version(path: str = "version") -> Version:
15+
def get_version(path: Union[str, os.PathLike]) -> semver.Version:
1416
"""
15-
Construct a Version from a file
17+
Construct a Version object from a file
1618
1719
:param path: A text file only containing the semantic version
1820
:return: A :class:`Version` object containing the semantic
1921
version from the file.
2022
"""
21-
with open(path,"r") as fh:
22-
version = fh.read().strip()
23+
version = open(path,"r").read().strip()
2324
return Version.parse(version)

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.