+ (which is the `default <https://forge.softwareheritage.org/H18>`_).
+4. **Review anything you want**: no matter the suggested reviewer(s),
+ feel free to review any outstanding CR.
+5. **One LGTM is enough**: feel free to approve any outstanding CR.
+6. **Review every day**: CRs should be timely as fellow developers
+ will wait for them.
+ To make CRs sustainable each developer should strive to dedicate
+ a fixed minimum amount of CR time every (work) day.
+
+For more detailed suggestions (and much more) on the motivational
+and practical aspects of code reviews see Good reads below.
+
+Good reads
+----------
+
+Good reads on various angles of code review:
+
+* `Best practices <https://medium.com/palantir/code-review-best-practices-19e02780015f>`_ (Palantir) ← comprehensive and recommended read, especially if you're short on time
+Here is a list of common gotchas when formatting Python docstrings for [http://www.sphinx-doc.org/en/stable/ Sphinx] and the [http://www.sphinx-doc.org/en/stable/ext/napoleon.html Napoleon] style.
+
+Sphinx
+------
+
+Lists
++++++
+
+All sorts of `lists <http://www.sphinx-doc.org/en/stable/rest.html#lists-and-quote-like-blocks>`_
+require an empty line before the first bullet and after the last one,
+to be properly interpreted as list.
+No indentation is required for list elements w.r.t. surrounding text,
+and line continuations should be indented like the first character
+after the bullet
+
+Bad::
+
+ this is a bad example that will not be interpreted as a list
+ preceding text
+ - foo
+ - bar
+ - baz
+ following text
+
+Good::
+
+ this is some text preceding the list
+
+ - foo
+ - bar
+ - baz
+ - this is a rather long-ish paragraph inserted in the list
+ with line continuation
+ - qux
+
+ this is some text following the list
+
+Bad::
+
+ - foo
+ - nested lists also requires empty lines, but they are missing here
+e.g., for code examples, requires double colon at the end of a line,
+then an empty line, and then the code block itself, indented:
+
+Bad::
+
+ This does not work as there is a single column and no empty line before code:
+ def foo(bar, baz):
+ qux = bar + baz
+
+ return qux
+
+Good::
+<pre>
+ a nice example of python code follows::
+
+ def foo(bar, baz):
+ qux = bar + baz
+
+ return qux
+
+ here we can restart text flow
+
+*Inline code samples* use double backquotes, and not single ones.
+
+Bad::
+
+ you have to instantiate the method `def foo(bar): pass`
+ in order to use this abstract class
+
+Good:
+
+ you have to instantiate the method ``def foo(bar): pass``
+ in order to use this abstract class
+
+=== ``**kwargs``, ``**args`` ===
+
+`Asterisks needs to be escaped <http://www.sphinx-doc.org/en/stable/rest.html#inline-markup>`_
+to avoid capture by emphasis markup.
+In case of multiple adjacent asterisks, escaping the first one is enough.
+
+Bad::
+
+ additional **kwargs are copied in the returned dictionary
+
+Good:
+
+ additional \**kwargs are copied in the returned dictionary
+
+Code cross-references
++++++++++++++++++++++
+
+Backquotes are not enough to cross-reference a Python entity
+(class, function, module, etc.); you need to use
+`Sphinx domains <http://www.sphinx-doc.org/en/stable/domains.html>`_ for that,
+and in particular the `Python domain <http://www.sphinx-doc.org/en/stable/domains.html#the-python-domain>`_
+
+Bad::
+
+ see the `do_something` function and the `swh.useless` module
+ for more information
+
+Good::
+
+ see the :func:`do_something` function and the :mod:`swh.useless` module
+ for more information
+
+Good::
+
+ you can avoid a long, fully-qualified anchor setting an
+ :func:`explicit label <swh.long.namespace.function>` for a link
+
+See also: the `list of Python roles <http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects>`_
+that you can use to cross-reference Python objects.
+Note that you can (and should) omit the <code>:py:</code> prefix,
+as Python is the default domain.
+
+Note also that when building Sphinx documentation
+for individual Software Heritage modules in isolation,
+cross-references to other modules will *not* be resolvable.
+But they will be resolvable when building the unified documentation
+from ``swh-docs``
+
+Napoleon
+--------
+
+Docstring sections
+++++++++++++++++++
+
+See the `list of docstring sections <http://www.sphinx-doc.org/en/stable/ext/napoleon.html#docstring-sections>`_
+supported by Napoleon.
+Everything else will *not* be typeset with a dedicated heading,
+you will have to do so explicitly using reStructuredText markup.
+
+Args
+++++
+
+Entries in Args section do *not* start with bullets, but just with argument names (as any other Napoleon section).
+Continuation lines should be indented.
+
+Bad::
+
+ Args:
+ - foo (int): first argument
+ - bar: second argument
+ - baz (bool): third argument
+
+Good::
+
+ Args:
+ foo (int): first argument
+ bar: second argument, which happen to have a fairly
+ long description of what it does
+ baz (bool): third argument
+
+Returns
++++++++
+
+In Returns section you need to use ":" carefully as, if present, it will be interpreted as a separator between return type and description. Also, the description of return value should not start on the same line of "Returns:", but on the subsequent one, indented.
+
+Bad::
+
+ Returns:
+ this does not work (colon will be interpreted as type/desc separator), a dict with keys:
+
+ - foo
+ - bar
+
+Good::
+
+ Returns:
+ this works (there is no colon) a dict with keys
+
+ - foo
+ - bar
+
+Good::
+
+ Returns:
+ dict: this works again (*first* colon identifies the type) a dict with keys:
+
+ - foo
+ - bar
+
+Bad::
+
+ Returns: this is not good either, you need to start a paragraph
+
+Raises
+++++++
+
+You need a ":" separator between exception names and their description.
+
+Bad::
+
+ Raises:
+ ValueError if you botched it
+ RuntimeError if we botched it
+
+
+Good::
+
+ Raises:
+ ValueError: if you botched it
+ RuntimeError: if we botched it
+
+See also
+--------
+
+* :ref:`python-style-guide`
diff --git a/docs/index.rst b/docs/index.rst
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,6 +13,14 @@
* :ref:`developer-setup` → get a working development setup that allows to hack
on the Software Heritage software stack
+Contributing
+------------
+
+* :ref:`patch-submission` → learn how to submit your patches to the
+ Software Heritage codebase
+* :ref:`code-review` → rules and guidelines to review code in
+ Software Heritage
+* :ref:`python-style-guide` → how to format the Python code you write