Add basic contribution guide

contribute.rst

@@ -0,0 +1,65 @@
+******************
+Contribution Guide
+******************
+
+If you want to contribute code to the TriFinger repositories, please keep the following
+guidelines in mind.  They are valid for all the repositories listed in
+:doc:`references/package_overview`.  Some, like code formatting, are automatically
+checked on pull requests, so you may only merge if those checks pass.
+
+
+Code Style
+==========
+
+General
+-------
+
+- Avoid abbreviations in variable/function/... names, rather use longer but more
+  descriptive names.  Example: ``joint_position`` instead of ``jnt_pos``.
+- When a variable holds a value with a unit, consider adding that unit as suffix.
+  Example: ``sleep_duration_ms``, ``joint_position_rad``.
+- Do not merge FIXME commands to the master branch.  They are okay as a reminder during
+  development on a feature branch but must be resolved before merging.
+- TODO comments are allowed but should be avoided if possible.
+- Never merge unsquashed fixup commits (generated by ``git commit --fixup``) to master.
+
+
+Python
+------
+
+All Python code must be formatted with black_ and should generally adhere to `PEP 8`_
+(except for the line length, which for some packages uses black's default of 88).
+
+Add docstrings to all classes and functions.  Format them using `Google style`_.
+
+
+C++
+---
+
+C++ code must be formatted with ``clang-format``, using the `configuration shipped with
+mpi_cmake_modules <clang_format_config_>`__.
+
+When you have the ``mpi_cmake_modules`` package installed in your workspace (which is
+likely the case, as it's a core dependency of the TriFinger packages), there is an
+executable ``mpi_cpp_format`` which will run ``clang-format`` with the correct
+configuration:
+
+.. code-block:: bash
+
+   mpi_cpp_format path/to/package
+
+
+Apart from that some basic style guide:
+
+- Class names start with a capital letter: ``MyAwesomeClass``
+- Variables and functions use snake case: ``my_awesome_variable``
+- Constants are ``ALL_UPPER_CASE``
+- Use ``#pragma once`` in header files.
+- Add doxygen comments to all classes and functions.
+
+
+
+.. _black: https://black.readthedocs.io/en/stable/
+.. _PEP 8: https://peps.python.org/pep-0008/
+.. _Google style: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
+.. _clang_format_config: https://github.com/machines-in-motion/mpi_cmake_modules/blob/master/resources/_clang-format

index.rst

@@ -55,6 +55,7 @@ Content
    howto/howto_setup_pc.rst
    howto/installation
    apptainer
+   contribute
 
 .. toctree::
    :caption: References