documentation: update contributing guide

Co-Authored-by: Pascal Repond <[email protected]>

Author: PascalRepond

Diff for: CONTRIBUTING.rst

@@ -1,6 +1,6 @@
 ..
     RERO ILS
-    Copyright (C) 2019 RERO
+    Copyright (C) 2019-2022 RERO+
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU Affero General Public License as published by
@@ -24,13 +24,13 @@ little bit helps, and credit will always be given.
 Types of Contributions
 ----------------------
 
-Security  Reports
-~~~~~~~~~~~~~~~~~
+Security reports
+~~~~~~~~~~~~~~~~
 
 In case you identified a security issue on the project, please report it to the
 e-mail address given in the `security policy`_.
 
-Report Bugs
+Bug reports
 ~~~~~~~~~~~
 
 Report bugs at https://github.com/rero/rero-ils/issues.
@@ -41,8 +41,8 @@ If you are reporting a bug, please include:
 * Any details about your local setup that might be helpful in troubleshooting.
 * Detailed steps to reproduce the bug.
 
-Fix Bugs
-~~~~~~~~
+Bug fixes
+~~~~~~~~~
 
 Look through the GitHub issues for bugs. Anything tagged with "bug"
 is open to whoever wants to implement it.
@@ -76,71 +76,76 @@ If you are proposing a feature:
 Get Started!
 ------------
 
-Ready to contribute? Here's how to set up ``rero-ils`` for local development.
+Ready to contribute? See the `installation procedure`_ to setup a local
+development environment.
 
-1. Fork the ``rero/rero-ils`` repo on GitHub.
-2. Clone your fork locally:
 
-   .. code-block:: console
 
-      $ git clone [email protected]:your_name_here/rero-ils.git
-
-3. Install your local using the `installation procedure`_.
-
-4. Create a branch for local development:
-
-   .. code-block:: console
-
-      $ git checkout -b name-of-your-bugfix-or-feature
-
-   Now you can make your changes locally.
-
-5. When you're done making changes, check that your changes pass tests:
+Pull Request Guidelines
+-----------------------
 
-   .. code-block:: console
+Before you submit a pull request, check that it meets these guidelines:
 
-      $ ./run-tests.sh
+1. The pull request should include tests and should not decrease test coverage.
+2. Your code is as clear as possible and sufficiently documented (comments, 
+   docstrings, ...).
+3. All tests on GitHub Actions should pass before merging.
 
-   The tests will provide you with test coverage and also check PEP8
-   (code style), PEP257 (documentation), flake8 as well as build the Sphinx
-   documentation and run doctests.
+Commit message style
+~~~~~~~~~~~~~~~~~~~~
 
-6. Add the ``.gitmessage.txt`` file to your ``git`` configuration:
+Your commit message should follow Invenio's `style guide`_. Commit message is first and foremost about the content. You are communicating
+with fellow developers, so be clear and brief.
 
-   .. code-block:: console
+(Inspired by `How to Write a Git Commit Message
+<https://chris.beams.io/posts/git-commit/>`_)
 
-        # globally
-        $ git config --global commit.template /path/.gitmessage.txt
+1. `Separate subject from body with a blank line.
+   <https://chris.beams.io/posts/git-commit/#separate>`_
+2. `Limit the subject line to 50 characters.
+   <https://chris.beams.io/posts/git-commit/#limit-50>`_
+3. Indicate the component followed by a short description
+4. `Do not end the subject line with a period.
+   <https://chris.beams.io/posts/git-commit/#end>`_
+5. `Use the imperative mood in the subject line.
+   <https://chris.beams.io/posts/git-commit/#imperative>`_
+6. `Wrap the body at 72 characters.
+   <https://chris.beams.io/posts/git-commit/#wrap-72>`_
+7. `Use the body to explain what and why vs. how, using bullet points. <https://chris.beams.io/posts/git-commit/#why-not-how>`_
 
-        # locally
-        $ git config --local commit.template .gitmessage.txt
+For example::
 
-   The ``Signed-off-by`` message is not used anymore, so you can avoid ``-s``
-   parameters when committing. But of course, you can modify your own version
-   of the ``.gitcommit.txt`` in order to add you own ``Co-Authored-by`` message.
+   component: summarize changes in 50 char or less
 
-7. Commit your changes and push your branch to GitHub:
+    * More detailed explanatory text, if necessary. Formatted using
+      bullet points, preferably `*`. Wrapped to 72 characters.
 
-   .. code-block:: console
+    * Explain the problem that this commit is solving. Focus on why you
+      are making this change as opposed to how (the code explains that).
+      Are there side effects or other unintuitive consequences of this
+      change? Here's the place to explain them.
 
-      $ git add .
-      $ git commit -s
-      $ git push origin name-of-your-bugfix-or-feature
+    * Data Migration Instructions: if your PR makes changes to the data model
+      or needs an action when updating an existing instance, include
+      migration instructions (e.g. needs item reindexing, needs update mapping).
+      It is even better if you can also include an Alembic script directly in
+      your PR.
 
-8. Submit a pull request through the GitHub website.
+    * Use words like "Adds", "Fixes" or "Breaks" in the listed bullets to help
+      others understand what you did.
 
-Pull Request Guidelines
------------------------
+    * If your commit closes or addresses an issue in the same project, you can
+      mention it in any of the bullets after the dot (closes #XXX). If it
+      addresses an issue from another project, mention the full issue URL
+      (Closes https://github.com/rero/rero-ils/issues/XXX).
 
-Before you submit a pull request, check that it meets these guidelines:
+   Co-authored-by: John Doe <[email protected]>
 
-1. The pull request should include tests and must not decrease test coverage.
-2. If the pull request adds functionality, the docs should be updated. Put
-   your new functionality into a function with a docstring.
-3. The pull request should work for Python 2.7, 3.3, 3.4 and 3.5. Check
-   https://travis-ci.org/rero/rero-ils/pull_requests
-   and make sure that the tests pass for all supported Python versions.
+**Git signature:** The only signature we use is ``Co-authored-by`` (see above)
+to provide credit to co-authors. Previously we required a ``Signed-off-by``
+signature, however this is no longer required.
 
 .. References:
 .. _installation procedure: INSTALL.rst
 .. _security policy: SECURITY.rst
+.. _style guide: https://github.com/inveniosoftware/invenio/blob/master/CONTRIBUTING.rst#commit-messages