diff --git a/CONTRIBUTORS b/CONTRIBUTORS index 205de33a..98d1d623 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -33,6 +33,7 @@ Significant contributors * Peter Bittner * robi-wan * T. Jameson Little +* Tom Schraitle * Tuure Laurinolli * Tyler Cross * Zack Lalanne diff --git a/docs/conf.py b/docs/conf.py index 786d444e..c2b49f49 100644 --- 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 index 05542d29..ed0bdf89 100644 --- 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