python-semver · s-celles · Oct 1, 2019 · Sep 30, 2019 · Oct 1, 2019
diff --git a/CONTRIBUTORS b/CONTRIBUTORS
@@ -33,6 +33,7 @@ Significant contributors
 * Peter Bittner <django@bittner.it>
 * robi-wan <robi-wan@suyu.de>
 * T. Jameson Little <t.jameson.little@gmail.com>
+* Tom Schraitle <tom_schr@web.de>
 * Tuure Laurinolli <tuure@laurinolli.net>
 * Tyler Cross <tyler@crosscollab.com>
 * Zack Lalanne <zack.lalanne@gmail.com>

diff --git a/docs/conf.py b/docs/conf.py
@@ -171,8 +171,3 @@
      author, 'semver', 'One line description of project.',
      'Miscellaneous'),
 ]
-
-
-intersphinx_mapping = {
-    "matplotlib": ('http://matplotlib.org', None),
-}
diff --git a/docs/development.rst b/docs/development.rst
@@ -1,12 +1,21 @@
 Contributing to semver
 ======================
 
-When you make changes to the code please run the tests before pushing your
-code to your fork and opening a `pull request`_:
+Do you want to contribute? Great! We would like to give you some
+helpful tips and tricks.
+When you make changes to the code, we would greatly appreciate if you
+consider the following requirements:
 
-.. code-block:: bash
+* 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.
+
+* Write test cases if you implement a new feature.
 
-    python setup.py test
+* Test also for side effects of your new feature and run the complete
+  test suite.
+* Document the new feature.
 
 We use `pytest`_ and `tox`_ to run tests against all supported Python
 versions.  All test dependencies are resolved automatically, apart from
@@ -16,13 +25,60 @@ virtualenv, which for the moment you still may have to install manually:
 
     pip install "virtualenv<14.0.0"  # <14.0.0 needed for Python 3.2 only
 
-You can use the ``clean`` command to remove build and test files and folders:
+We recommend to use the following workflow if you would like to contribute:
 
-.. code-block:: bash
+1. Fork our project on GitHub using this link:
+   https://github.com/k-bx/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
+   * ``bugfix/123-fix-security-bar`` when dealing with bugfixes
+
+   Use this :command:`git` command::
+
+   $ git checkout -b feature/NAME_OF_YOUR_FEATURE
+
+4. Work on your branch. Commit your work. Don't forget to write test cases
+   for your new feature.
+
+5. Run the test suite. You have the following options:
+
+   * To run a complete test use the ``setup.py`` script (shown for Python 3)::
+
+     $ python3 setup.py test
+
+    This may create some errors as you probably do not have all Python
+    versions installed on your system. To restrict it to only installed
+    version (probably 2.7 and 3.x), pass this options::
+
+     $ python3 setup.py test -a --skip-missing-interpreters
+
+   * To run a test for a specific Python version, use the
+     :command:`tox` command, for example, for Python 3.6::
+
+      $ tox -e py36
+
+6. Create a `pull request`_. Describe in the pull request what you did
+   and why. If you have open questions, ask.
+
+7. Wait for feedback. If you receive any comments, address these.
+
+8. After your pull request got accepted, delete your branch.
+
+9. Use the ``clean`` command to remove build and test files and folders::
 
-    python setup.py clean
+   $ python setup.py clean
 
 
 .. _pull request: https://github.com/k-bx/python-semver/pulls
 .. _pytest: http://pytest.org/
-.. _tox: http://tox.testrun.org/
+.. _tox: https://tox.readthedocs.org/
+.. _Semantic Versioning: https://semver.org