Reorganize "Contributing" documentation to be more accessible to new contributors (#573)

* Reorganize "Contributing" documentation to be more accessible to new contributors

The following changes were done:

- move "How to contribute" first, and "Set up a dev environment" as the
  second section.  This way, a new contributor has access to the most
  general information first, instead of the very specific "dev
  environment" documentation.

- reduce "How to contribute" / "As a developer" by moving the part about
  tests to a new "Contributing as a developer" section (see below).  This
  way, all types of contributions get roughly the same amount of text in
  the first "How to contribute" section.

- add a new "Contributing as a developer" section, which lists items that
  are useful when preparing a code contribution (running tests, formatting
  code, create database migration).  These items were moved either from
  "How to contribute" or from "Set up a dev environment".

* Add brief documentation about updating and adding tests

Co-authored-by: Baptiste Jonglez <git@bitsofnetworks.org>

1 files changed, 99 insertions, 66 deletions

diff --git a/docs/contributing.rst b/docs/contributing.rst
index 27f890b..3401524 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -1,6 +1,56 @@
 Contributing
 ############
 
+.. _how-to-contribute:
+
+How to contribute
+=================
+
+You would like to contribute? First, thanks a bunch! This project is a small
+project with just a few people behind it, so any help is appreciated!
+
+There are different ways to help us, regarding if you are a designer,
+a developer or an user.
+
+As a developer
+--------------
+
+If you want to contribute code, you can write it and then issue a pull request
+on github. To get started, please read :ref:`setup-dev-environment` and
+:ref:`contributing-developer`.
+
+As a designer / Front-end developer
+-----------------------------------
+
+Feel free to provide mockups, or to involve yourself in the discussions
+happening on the GitHub issue tracker. All ideas are welcome. Of course, if you
+know how to implement them, feel free to fork and make a pull request.
+
+As a translator
+---------------
+
+If you're able to translate Ihatemoney in your own language,
+head over to `the website we use for translations <https://hosted.weblate.org/projects/i-hate-money/i-hate-money/>`_
+and start translating.
+
+All the heavy lifting will be done automatically, and your strings will
+eventually be integrated.
+
+Once a language is ready to be integrated, add it to the
+``SUPPORTED_LANGUAGES`` list, in ``ihatemoney/default_settings.py``.
+
+End-user
+--------
+
+You are using the application and found a bug? You have some ideas about how to
+improve the project? Please tell us `by filling a new issue <https://github.com/spiral-project/ihatemoney/issues>`_.
+Or, if you prefer, you can send me an e-mail to `alexis@notmyidea.org` and I
+will update the issue tracker with your feedback.
+
+Thanks again!
+
+.. _setup-dev-environment:
+
 Set up a dev environment
 ========================
 
@@ -45,39 +95,6 @@ In case you want to update to newer versions (from Git), you can just run the "u
 
   make update
 
-Create database migrations
---------------------------
-
-In case you need to modify the database schema, first make sure that you have
-an up-to-date database by running the dev server at least once (the quick way
-or the hard way, see above).  The dev server applies all existing migrations
-when starting up.
-
-You can now update the models in ``ihatemoney/models.py``. Then run the following
-command to create a new database revision file::
-
-  make create-database-revision
-
-If your changes are simple enough, the generated script will be populated with
-the necessary migrations steps. You can view and edit the generated script, which
-is useful to review that the expected model changes have been properly detected.
-Usually the auto-detection works well in most cases, but you can of course edit the
-script to fix small issues.  You could also edit the script to add data migrations.
-
-When you are done with your changes, don't forget to add the migration script to
-your final git commit!
-
-If the migration script looks completely wrong, remove the script and start again
-with an empty database.  The simplest way is to remove or rename the dev database
-located at ``/tmp/ihatemoney.db``, and run the dev server at least once.
-
-For complex migrations, it is recommended to start from an empty revision file
-which can be created with the following command::
-
-  make create-empty-database-revision
-
-You then need to write the migration steps yourself.
-
 Useful settings
 ----------------
 
@@ -93,26 +110,38 @@ Then before running the application, declare its path with ::
 
   export IHATEMONEY_SETTINGS_FILE_PATH="$(pwd)/settings.cfg"
 
-How to contribute
-=================
+.. _contributing-developer:
 
-You would like to contribute? First, thanks a bunch! This project is a small
-project with just a few people behind it, so any help is appreciated!
+Contributing as a developer
+===========================
 
-There are different ways to help us, regarding if you are a designer,
-a developer or an user.
+All code contributions should be submitted as Pull Requests on the
+`github project <https://github.com/spiral-project/ihatemoney>`_.
 
-As a developer
---------------
+Below are some points that you should check to help you prepare your Pull Request.
 
-If you want to contribute code, you can write it and then issue a pull request
-on github. Please, think about updating and running the tests before asking for
-a pull request as it will help us to maintain the code clean and running.
+Running tests
+-------------
+
+Please, think about updating and running the tests before asking for a pull request
+as it will help us to maintain the code clean and running.
 
-To do so::
+To run the tests::
 
     make test
 
+Tests can be edited in ``ihatemoney/tests/tests.py``. If some test cases fail because
+of your changes, first check whether your code correctly handle these cases.
+If you are confident that your code is correct and that the test cases simply need
+to be updated to match your changes, update the test cases and send them as part of
+your pull request.
+
+If you are introducing a new feature, you need to either add tests to existing classes,
+or add a new class (if your new feature is significantly different from existing code).
+
+Formatting code
+---------------
+
 We are using `black <https://black.readthedocs.io/en/stable/>`_ and
 `isort <https://timothycrosley.github.io/isort/>`_ formatters for all the Python
 files in this project. Be sure to run it locally on your files.
@@ -123,35 +152,39 @@ To do so, just run::
 You can also integrate them with your dev environment (as a *format-on-save*
 hook, for instance).
 
-As a designer / Front-end developer
------------------------------------
+Creating database migrations
+----------------------------
 
-Feel free to provide mockups, or to involve yourself in the discussions
-happening on the GitHub issue tracker. All ideas are welcome. Of course, if you
-know how to implement them, feel free to fork and make a pull request.
+In case you need to modify the database schema, first make sure that you have
+an up-to-date database by running the dev server at least once (the quick way
+or the hard way, see above).  The dev server applies all existing migrations
+when starting up.
 
-As a translator
----------------
+You can now update the models in ``ihatemoney/models.py``. Then run the following
+command to create a new database revision file::
 
-If you're able to translate Ihatemoney in your own language,
-head over to `the website we use for translations <https://hosted.weblate.org/projects/i-hate-money/i-hate-money/>`_
-and start translating.
+  make create-database-revision
 
-All the heavy lifting will be done automatically, and your strings will
-eventually be integrated.
+If your changes are simple enough, the generated script will be populated with
+the necessary migrations steps. You can view and edit the generated script, which
+is useful to review that the expected model changes have been properly detected.
+Usually the auto-detection works well in most cases, but you can of course edit the
+script to fix small issues.  You could also edit the script to add data migrations.
 
-Once a language is ready to be integrated, add it to the
-``SUPPORTED_LANGUAGES`` list, in ``ihatemoney/default_settings.py``.
+When you are done with your changes, don't forget to add the migration script to
+your final git commit!
 
-End-user
---------
+If the migration script looks completely wrong, remove the script and start again
+with an empty database.  The simplest way is to remove or rename the dev database
+located at ``/tmp/ihatemoney.db``, and run the dev server at least once.
 
-You are using the application and found a bug? You have some ideas about how to
-improve the project? Please tell us `by filling a new issue <https://github.com/spiral-project/ihatemoney/issues>`_.
-Or, if you prefer, you can send me an e-mail to `alexis@notmyidea.org` and I
-will update the issue tracker with your feedback.
+For complex migrations, it is recommended to start from an empty revision file
+which can be created with the following command::
+
+  make create-empty-database-revision
+
+You then need to write the migration steps yourself.
 
-Thanks again!
 
 How to build the documentation ?
 ================================