From c18db7d37ec421e98132fc75390fff016ef22f34 Mon Sep 17 00:00:00 2001 From: Federico Capoano Date: Mon, 15 May 2017 20:06:53 +0200 Subject: [PATCH] [docs] Improved contributing guidelines #69 Closes #69 --- docs/source/general/contributing.rst | 118 +++++++++++++++++++-------- 1 file changed, 83 insertions(+), 35 deletions(-) diff --git a/docs/source/general/contributing.rst b/docs/source/general/contributing.rst index 65e79d2e2..ebfa80cee 100644 --- a/docs/source/general/contributing.rst +++ b/docs/source/general/contributing.rst @@ -2,69 +2,117 @@ Contributing ============ -We welcome contributions and feedback! +.. raw:: html + +

+ + +

+ +Thank you for taking the time to contribute to netjsonconfig. + +Follow these guidelines to speed up the process. -If you intend to contribute in any way please keep the following guidelines in mind: +.. contents:: **Table of Contents**: + :backlinks: none + :depth: 3 -1. Announce your intentions in the `OpenWISP Mailing List `_ -2. :ref:`install_git_fork_for_contributing` -3. Follow `PEP8, Style Guide for Python Code `_ -4. Write code -5. Write tests for your code -6. Ensure all tests pass -7. Ensure test coverage does not decrease -8. Document your changes -9. Send pull request +Reach out before you start +-------------------------- +Before opening a new issue, try the following steps: -Virtual Environment -------------------- +- look if somebody else has already started working on the same issue + by looking in the `github issues `_ + and `pull requests `_ +- look also in the `OpenWISP mailing list `_ +- announce your intentions by opening a new issue +- present yourself on the mailing list -Please use a virtual environment while developing your feature, it keeps everybody on the same page and it helps reproducing bugs and resolving problems. +Create a virtual environment +---------------------------- + +Please use a `python virtual environment `_ while +developing your feature, it keeps everybody on the same page and it helps reproducing bugs +and resolving problems. + +We suggest you to use `virtualenvwrapper `_ for this task +(consult install instructions in the virtualenvwrapper docs). + +.. code-block:: shell + + mkvirtualenv netjsonconfig # create virtualenv + +Fork repo and install your fork +------------------------------- + +Once you have forked this repository to your own github account or organization, +install your own fork in your development environment: .. code-block:: shell - virtualenv env - source env/bin/activate + git clone git@github.com:/netjsonconfig.git + cd netjsonconfig + workon netjsonconfig # activate virtualenv python setup.py develop -.. note:: +Ensure test coverage does not decrease +-------------------------------------- - Another choice is using ``virtualenvwrapper``, they are equivalent tools but ``virtualenvwrapper`` is nicer to use +First of all, install the test requirements: -Style guide enforcement ------------------------ +.. code-block:: shell -Install ``flake8`` and ``isort`` to check for common pitfalls that may have your contribution stopped, they are listed in ``requirements-test.txt`` with the other testing requirements + workon netjsonconfig # activate virtualenv + pip install -r requirements-test.txt + +When you introduce changes, ensure test coverage is not decreased with: + +.. code-block:: shell + + nosetests --with-coverage --cover-package=netjsonconfig + +Follow style conventions (PEP8, isort) +-------------------------------------- + +First of all, install the test requirements: .. code-block:: shell - source env/bin/activate + workon netjsonconfig # activate virtualenv pip install -r requirements-test.txt -Before committing your work and opening a pull request run this to check +Before committing your work check that your changes are not breaking the style conventions with: .. code-block:: shell ./runflake8 && ./runisort -.. note:: - To speed things up you can add your virtual environment directory to the list of the excluded directories in the ``runflake8`` script +For more information, please see: + +- `PEP8: Style Guide for Python Code `_ +- `isort: a python utility / library to sort imports `_ -Building documentation ----------------------- +Update the documentation +------------------------ -To build the documentation for this project please install sphinx inside the virtual environment +If you introduce new features or change existing documented behavior, +please remember to update the documentation! + +The documentation is located in the ``/docs`` directory +of the repository. + +To do work on the docs, proceed with the following steps: .. code-block:: shell - source env/bin/activate + workon netjsonconfig # activate virtualenv pip install sphinx - cd doc && make html + cd docs + make html -.. raw:: html +Send pull request +----------------- -

- - -

+Now is time to push your changes to github and open a `pull request +`_!