python-semver · tomschr · Mar 19, 2023 · Mar 5, 2023
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -8,6 +8,7 @@ The semver source code is managed using Git and is hosted on GitHub::
    git clone git://github.com/python-semver/python-semver
 
 
+
 Reporting Bugs and Asking Questions
 -----------------------------------
 
@@ -34,193 +35,14 @@ consider the following general requirements:
   If not, ask on its GitHub project https://github.com/semver/semver.
 
 
+More topics
+-----------
 
-Modifying the Code
-------------------
-
-We recommend the following workflow:
-
-#. Fork our project on GitHub using this link:
-   https://github.com/python-semver/python-semver/fork
-
-#. Clone your forked Git repository (replace ``GITHUB_USER`` with your
-   account name on GitHub)::
-
-    $ git clone git@github.com:GITHUB_USER/python-semver.git
-
-#. Create a new branch. You can name your branch whatever you like, but we
-   recommend to use some meaningful name. If your fix is based on a
-   existing GitHub issue, add also the number. Good examples would be:
-
-   * ``feature/123-improve-foo`` when implementing a new feature in issue 123
-   * ``bugfix/234-fix-security-bar`` a bugfixes for issue 234
-
-   Use this :command:`git` command::
-
-   $ git checkout -b feature/NAME_OF_YOUR_FEATURE
-
-#. Work on your branch and create a pull request:
-
-   a. Write test cases and run the complete test suite, see :ref:`testsuite`
-      for details.
-
-   b. Write a changelog entry, see section :ref:`add-changelog`.
-
-   c. If you have implemented a new feature, document it into our
-      documentation to help our reader. See section :ref:`doc` for
-      further details.
-
-   d. Create a `pull request`_. Describe in the pull request what you did
-      and why. If you have open questions, ask.
-
-#. Wait for feedback. If you receive any comments, address these.
-
-#. After your pull request got accepted, delete your branch.
-
-
-.. _testsuite:
-
-Running the Test Suite
-----------------------
-
-We use `pytest`_ and `tox`_ to run tests against all supported Python
-versions.  All test dependencies are resolved automatically.
-
-You can decide to run the complete test suite or only part of it:
-
-* To run all tests, use::
-
-     $ tox
-
-  If you have not all Python interpreters installed on your system
-  it will probably give you some errors (``InterpreterNotFound``).
-  To avoid such errors, use::
-
-     $ tox --skip-missing-interpreters
-
-  It is possible to use one or more specific Python versions. Use the ``-e``
-  option and one or more abbreviations (``py37`` for Python 3.7,
-  ``py38`` for Python 3.8 etc.)::
-
-      $ tox -e py37
-      $ tox -e py37,py38
-
-  To get a complete list and a short description, run::
-
-      $ tox -av
-
-* To run only a specific test, pytest requires the syntax
-  ``TEST_FILE::TEST_FUNCTION``.
-
-  For example, the following line tests only the function
-  :func:`test_immutable_major` in the file :file:`test_bump.py` for all
-  Python versions::
-
-      $ tox -e py37 -- tests/test_bump.py::test_should_bump_major
-
-  By default, pytest prints only a dot for each test function. To
-  reveal the executed test function, use the following syntax::
-
-     $ tox -- -v
-
-  You can combine the specific test function with the ``-e`` option, for
-  example, to limit the tests for Python 3.7 and 3.8 only::
-
-      $ tox -e py37,py38 -- tests/test_bump.py::test_should_bump_major
-
-Our code is checked against formatting, style, type, and docstring issues
-(`black`_, `flake8`_, `mypy`_, and `docformatter`_).
-It is recommended to run your tests in combination with :command:`checks`,
-for example::
-
-   $ tox -e checks,py37,py38
-
-
-.. _doc:
-
-Documenting semver
-------------------
-
-Documenting the features of semver is very important. It gives our developers
-an overview what is possible with semver, how it "feels", and how it is
-used efficiently.
-
-.. note::
-
-    To build the documentation locally use the following command::
-
-      $ tox -e docs
-
-    The built documentation is available in :file:`docs/_build/html`.
-
-
-A new feature is *not* complete if it isn't proberly documented. A good
-documentation includes:
-
-  * **A docstring**
-
-    Each docstring contains a summary line, a linebreak, an optional
-    directive (see next item), the description of its arguments in
-    `Sphinx style`_, and an optional doctest.
-    The docstring is extracted and reused in the :ref:`api` section.
-    An appropriate docstring should look like this::
-
-         def to_tuple(self) -> VersionTuple:
-            """
-            Convert the Version object to a tuple.
-
-            .. versionadded:: 2.10.0
-               Renamed ``VersionInfo._astuple`` to ``VersionInfo.to_tuple`` to
-               make this function available in the public API.
-
-            :return: a tuple with all the parts
-
-            >>> semver.Version(5, 3, 1).to_tuple()
-            (5, 3, 1, None, None)
-            """
-
-  * **An optional directive**
-
-    If you introduce a new feature, change a function/method, or remove something,
-    it is a good practice to introduce Sphinx directives into the docstring.
-    This gives the reader an idea what version is affected by this change.
-
-    The first required argument, ``VERSION``, defines the version when this change
-    was introduced. You can choose from:
-
-    * ``.. versionadded:: VERSION``
-
-      Use this directive to describe a new feature.
-
-    * ``.. versionchanged:: VERSION``
-
-      Use this directive to describe when something has changed, for example,
-      new parameters were added, changed side effects, different return values, etc.
-
-    * ``.. deprecated:: VERSION``
-
-      Use this directive when a feature is deprecated. Describe what should
-      be used instead, if appropriate.
-
-
-    Add such a directive *after* the summary line, as shown above.
-
-  * **The documentation**
-
-    A docstring is good, but in most cases it's too dense. API documentation
-    cannot replace a good user documentation. Describe how
-    to use your new feature in our documentation. Here you can give your
-    readers more examples, describe it in a broader context or show
-    edge cases.
-
-
-.. _add-changelog:
-
-Adding a Changelog Entry
-------------------------
-
-.. include:: ../changelog.d/README.rst
-    :start-after: -text-begin-
+* `Running the Test Suite <docs/contribute/run-test-suite.rst>`_
+* `Documenting semver <docs/contribute/doc-semver.rst>`_
+* `Adding a Changelog Entry <docs/contribute/add-changelog-entry.rst>`_
+* `Preparing the Release <docs/contribute/release-procedure.rst>`_
+* `Finish the Release <docs/contribute/finish-release.rst>`_
 
 
 .. _black: https://black.rtfd.io

diff --git a/CONTRIBUTORS b/CONTRIBUTORS
@@ -22,30 +22,37 @@ Old maintainer:
 * Kostiantyn Rybnikov <k-bx@k-bx.com>
 
 
-Significant contributors
-========================
+List of Contributors
+====================
 
-* Alexander Puzynia <werwolf.by@gmail.com>
-* Alexander Shorin <kxepal@gmail.com>
-* Anton Talevnin <TalAntR@users.noreply.github.com>
-* Ben Finney <ben+python@benfinney.id.au>
+(in alphabetical order)
+
+* Jelo Agnasin <jelo@icannhas.com>
 * Carles Barrobés <carles@barrobes.com>
-* Craig Blaszczyk <masterjakul@gmail.com>
-* Damien Nadé <anvil@users.noreply.github.com>
 * Eli Bishop <eli-darkly@users.noreply.github.com>
-* George Sakkis <gsakkis@users.noreply.github.com>
-* Jan Pieter Waagmeester <jieter@jieter.nl>
-* Jelo Agnasin <jelo@icannhas.com>
-* Karol Werner <karol.werner@ppkt.eu>
 * Peter Bittner <django@bittner.it>
-* robi-wan <robi-wan@suyu.de>
-* sbrudenell <sbrudenell@users.noreply.github.com>
+* Craig Blaszczyk <masterjakul@gmail.com>
+* Tyler Cross <tyler@crosscollab.com>
+* Dennis Felsing <def-@users.noreply.github.com>
+* Ben Finney <ben+python@benfinney.id.au>
+* Zane Geiger <zanecodes@users.noreply.github.com>
 * T. Jameson Little <t.jameson.little@gmail.com>
+* Raphael Krupinski <rafalkrupinski@users.noreply.github.com>
 * Thomas Laferriere <tlaferriere@users.noreply.github.com>
-* Tuure Laurinolli <tuure@laurinolli.net>
-* Tyler Cross <tyler@crosscollab.com>
 * Zack Lalanne <zack.lalanne@gmail.com>
-
+* Tuure Laurinolli <tuure@laurinolli.net>
+* Damien Nadé <anvil@users.noreply.github.com>
+* Jan Pieter Waagmeester <jieter@jieter.nl>
+* Alexander Puzynia <werwolf.by@gmail.com>
+* Lexi Robinson <Lexicality@users.noreply.github.com>
+* robi-wan <robi-wan@suyu.de>
+* George Sakkis <gsakkis@users.noreply.github.com>
+* Mike Salvatore <mssalvatore@users.noreply.github.com>
+* sbrudenell <sbrudenell@users.noreply.github.com>
+* Alexander Shorin <kxepal@gmail.com>
+* Anton Talevnin <TalAntR@users.noreply.github.com>
+* Karol Werner <karol.werner@ppkt.eu>
+
 ..
     Local variables:
     coding: utf-8

diff --git a/README.rst b/README.rst
@@ -1,8 +1,3 @@
-.. warning::
-
-   This is a development version. Do **NOT** use it
-   in production before the final 3.0.0 is released.
-
 Quickstart
 ==========
 

diff --git a/changelog.d/284.deprecation.rst b/changelog.d/284.deprecation.rst
diff --git a/changelog.d/284.doc.rst b/changelog.d/284.doc.rst
diff --git a/changelog.d/284.feature.rst b/changelog.d/284.feature.rst
diff --git a/changelog.d/344.bugfix.rst b/changelog.d/344.bugfix.rst
diff --git a/changelog.d/388.trivial.rst b/changelog.d/388.trivial.rst
diff --git a/changelog.d/pr384.bugfix.rst b/changelog.d/pr384.bugfix.rst
diff --git a/changelog.d/pr389.trivial.rst b/changelog.d/pr389.trivial.rst
diff --git a/changelog.d/pr392.doc.rst b/changelog.d/pr392.doc.rst
diff --git a/changelog.d/pr393.bugfix.rst b/changelog.d/pr393.bugfix.rst
diff --git a/changelog.d/pr396.bug.rst b/changelog.d/pr396.bug.rst
diff --git a/docs/advanced/convert-pypi-to-semver.rst b/docs/advanced/convert-pypi-to-semver.rst
@@ -135,7 +135,7 @@ semver:
     def convert2semver(ver: packaging.version.Version) -> semver.Version:
         """Converts a PyPI version into a semver version
 
-        :param packaging.version.Version ver: the PyPI version
+        :param ver: the PyPI version
         :return: a semver version
         :raises ValueError: if epoch or post parts are used
         """
@@ -145,7 +145,7 @@ semver:
             raise ValueError("Can't convert a post part to semver")
 
         pre = None if not ver.pre else "".join([str(i) for i in ver.pre])
-        semver.Version(*ver.release, prerelease=pre, build=ver.dev)
+        return semver.Version(*ver.release, prerelease=pre, build=ver.dev)
 
 
 .. _convert_semver_to_pypi:

diff --git a/docs/advanced/create-subclasses-from-version.rst b/docs/advanced/create-subclasses-from-version.rst
@@ -16,15 +16,16 @@ but the other behavior is the same, use the following code:
 
 
 The derived class :class:`SemVerWithVPrefix` can be used like
-the original class:
+the original class. Additionally, you can pass "incomplete"
+version strings like ``v2.3``:
 
 .. code-block:: python
 
      >>> v1 = SemVerWithVPrefix.parse("v1.2.3")
      >>> assert str(v1) == "v1.2.3"
      >>> print(v1)
      v1.2.3
-     >>> v2 = SemVerWithVPrefix.parse("v2.3.4")
+     >>> v2 = SemVerWithVPrefix.parse("v2.3")
      >>> v2 > v1
      True
      >>> bad = SemVerWithVPrefix.parse("1.2.4")

diff --git a/docs/advanced/index.rst b/docs/advanced/index.rst
@@ -3,6 +3,7 @@ Advanced topics
 
 
 .. toctree::
+    :maxdepth: 1
 
     deal-with-invalid-versions
     create-subclasses-from-version

diff --git a/docs/advanced/semverwithvprefix.py b/docs/advanced/semverwithvprefix.py
@@ -20,7 +20,7 @@ def parse(cls, version: str) -> "SemVerWithVPrefix":
                 f"{version!r}: not a valid semantic version tag. "
                 "Must start with 'v' or 'V'"
             )
-        return super().parse(version[1:])
+        return super().parse(version[1:], optional_minor_and_patch=True)
 
     def __str__(self) -> str:
         # Reconstruct the tag

diff --git a/docs/advanced/version-from-file.rst b/docs/advanced/version-from-file.rst
@@ -8,16 +8,17 @@ is to use the following function:
 
 .. code-block:: python
 
+    import os
+    from typing import Union
     from semver.version import Version
 
-    def get_version(path: str = "version") -> Version:
+    def get_version(path: Union[str, os.PathLike]) -> semver.Version:
         """
-        Construct a Version from a file
+        Construct a Version object from a file
 
         :param path: A text file only containing the semantic version
         :return: A :class:`Version` object containing the semantic
                  version from the file.
         """
-        with open(path,"r") as fh:
-            version = fh.read().strip()
+        version = open(path,"r").read().strip()
         return Version.parse(version)