The semver source code is managed using Git and is hosted on GitHub:

git clone git://github.com/python-semver/python-semver

If you think you have encountered a bug in semver or have an idea for a new feature? Great! We like to hear from you!

There are several options to participate:

• Open a new topic on our GitHub discussion page. Tell us our ideas or ask your questions.
• Look into our GitHub issues tracker or open a new issue.

Before you make changes to the code, we would highly appreciate if you consider the following general requirements:

• Make sure your code adheres to the Semantic Versioning specification.
• Check if your feature is covered by the Semantic Versioning specification. If not, ask on its GitHub project https://github.com/semver/semver.

We recommend the following workflow:

1. Fork our project on GitHub using this link: https://github.com/python-semver/python-semver/fork

2. Clone your forked Git repository (replace GITHUB_USER with your account name on GitHub):

   $ git clone git@github.com:GITHUB_USER/python-semver.git
   

3. 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
   

4. Work on your branch and create a pull request:

   1. Write test cases and run the complete test suite, see :ref:`testsuite` for details.
   2. Write a changelog entry, see section :ref:`add-changelog`.
   3. If you have implemented a new feature, document it into our documentation to help our reader. See section :ref:`doc` for further details.
   4. Create a pull request. Describe in the pull request what you did and why. If you have open questions, ask.

5. Wait for feedback. If you receive any comments, address these.

6. After your pull request got accepted, delete your branch.

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 (py36 for Python 3.6, py37 for Python 3.7 etc.):

  $ tox -e py36
  $ tox -e py36,py37
  

  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 py36 -- 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.6 and 3.7 only:

  $ tox -e py36,py37 -- 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,py36,py37

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.

$ tox -e docs

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.