[doc] add chapter on the purpose of (git) commits (#4729)

Chapter on the purpose of (git) commits

The commits and their messages are elementary for the traceability of changes
and are unfortunately still too often given too little attention.

It therefore seems necessary to dedicate a chapter to this topic in the context
of development.

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>

docs/dev/commits.rst

@@ -0,0 +1,108 @@
+.. _create commit:
+
+===============================
+Git Commits & Change Management
+===============================
+
+.. sidebar:: Create good commits!
+
+   - `Conventional Commits`_
+   - `Structural split of changes`_
+   - `Git Commit Good Practice`_
+
+A commit and its commit message are among the most important information
+available to a developer for bug fixing and further development.  A commit is a
+change and changes have a context (a change request).
+
+In a SCM system (git), the change history is derived from the commit history. A
+commit message is therefore part of the documentation for change management and
+thus elementary for the traceability of changes.
+
+**What a commit is not**: *A commit to an SCM system is not used to save files!*
+
+A commit should always have a context and the commit message describes what is
+to be changed in that context, just as a function description should describe
+what the intention and the goal of the function is, a commit message should
+describe what the intention and the goal of that commit is.
+
+The commit messages form the history and are the first and therefore most
+important information a developer has when he has to research when and why a
+change had to be made and how it was made (what the goal was).
+
+Like any text, a commit message should be written for the reader and not from
+the perspective of the author.
+
+When scrolling through the history, the first thing one see is the title of the
+commit message. Therefore the title should describe the change as briefly and
+precisely as possible ... followed by a blank line and then a somewhat detailed
+description of the change.
+
+----
+
+The follwing rules should be in mind, when creating a commit:
+
+- **Commit history should be read like a history book.**
+- **Commit messages are for the reader not for the author of the commit.**
+- **A commit is the atomic code-modification of a change in change management.**
+- **Think about which descriptions from your PR might belong in the commit message.**
+- **The maximum line length in a commit message is 80 characters.**
+
+----
+
+Choose meaningful commit messages:
+
+  .. code::
+
+     [type] optional scope: description
+
+     [body]
+
+     [optional trailers]
+
+``[type]``:
+  Commits MUST be prefixed with a type .. ``feat``, ``fix``, ``refactor``,
+  ``mod``, ``upd``, ``doc``, ``l10n``, ``build`` ..
+
+``[body]``
+  `Information in commit messages`_
+
+``[optional trailers]``:
+  - `Signed-off-by`_: certify that the committer has the rights to submit the
+    work under the project’s license.  That the developer has this right is a
+    prerequisite for a merge.  If the `Signed-off-by`_ is not set in the
+    commit, the contributor enters his `Developer's Certificate of Origin` at
+    the latest when creating a PR!
+  - Closes: Link to the bug report or the bug number (e.g. ``Closes: #10``)
+  - `Co-authored-by`_: email address of the co-author
+  - Reported-by: email address (if there is no bug report)
+  - Suggested-by: email address (if there is no bug report)
+
+----
+
+To give examples at hand, here are a few commits.  Follow the links to see the
+full commit messages:
+
+:patch:`44d941c93`
+  ``[fix] mojeek web engine: don't add empty fmt argument for web searches``
+
+:patch:`feb15e387`
+   ``[fix] brave.news engine: response is HTML and no longer JSON``
+
+:patch:`bdfe1c2a1`
+   ``[mod] engines: migration of the individual cache solutions to EngineCache``
+
+
+.. _Conventional Commits:
+    https://www.conventionalcommits.org/
+.. _Structural split of changes:
+    https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes
+.. _Git Commit Good Practice:
+    https://wiki.openstack.org/wiki/GitCommitMessages
+.. _Information in commit messages:
+    https://wiki.openstack.org/wiki/GitCommitMessages#Information_in_commit_messages
+.. _`Developer's Certificate of Origin`:
+    https://developercertificate.org/
+.. _Signed-off-by:
+    https://git-scm.com/docs/git-commit#Documentation/git-commit.txt-code--signoffcode
+.. _Co-authored-by:
+    https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors

docs/dev/contribution_guide.rst

@@ -30,15 +30,15 @@ SearXNG was born out of the need for a **privacy-respecting** search tool which
 can be extended easily to maximize both its search and its privacy protecting
 capabilities.
 
-Some widely used search engine features may work differently, 
-may be turned off by default, or may not be implemented at all in SearXNG 
+Some widely used search engine features may work differently,
+may be turned off by default, or may not be implemented at all in SearXNG
 **as a consequence of a privacy-by-design approach**.
 
 Following this approach, features reducing the privacy preserving aspects of SearXNG should be
 switched off by default or should not be implemented at all.  There are plenty of
 search engines already providing such features.  If a feature reduces
-SearXNG's efficacy in protecting a user's privacy, the user must be informed about 
-the effect of choosing to enable it.  Features that protect privacy but differ from the 
+SearXNG's efficacy in protecting a user's privacy, the user must be informed about
+the effect of choosing to enable it.  Features that protect privacy but differ from the
 expectations of the user should also be carefully explained to them.
 
 Also, if you think that something works weird with SearXNG, it might be because
@@ -56,20 +56,12 @@ Code
 ====
 
 .. _PEP8: https://www.python.org/dev/peps/pep-0008/
-.. _Conventional Commits: https://www.conventionalcommits.org/
-.. _Git Commit Good Practice: https://wiki.openstack.org/wiki/GitCommitMessages
 .. _Structural split of changes:
     https://wiki.openstack.org/wiki/GitCommitMessages#Structural_split_of_changes
-.. _gitmoji: https://gitmoji.carloscuesta.me/
-.. _Semantic PR: https://github.com/zeke/semantic-pull-requests
 
 .. sidebar:: Create good commits!
 
-   - `Structural split of changes`_
-   - `Conventional Commits`_
-   - `Git Commit Good Practice`_
-   - some like to use: gitmoji_
-   - not yet active: `Semantic PR`_
+   - :ref:`create commit`
 
 In order to submit a patch, please follow the steps below:
 
@@ -88,15 +80,7 @@ In order to submit a patch, please follow the steps below:
 
 - Add yourself to the :origin:`AUTHORS.rst` file.
 
-- Choose meaningful commit messages, read `Conventional Commits`_
-
-  .. code::
-
-     <type>[optional scope]: <description>
-
-     [optional body]
-
-     [optional footer(s)]
+- Choose meaningful commit messages, see :ref:`create commit`
 
 - Create a pull request.
 
@@ -161,7 +145,7 @@ changed (:ref:`make docs.clean`).
 
 Live builds are implemented by sphinx-autobuild_.  Use environment
 ``$(SPHINXOPTS)`` to pass arguments to the sphinx-autobuild_ command.  You can
-pass any argument except for the ``--host`` option (which is always set to ``0.0.0.0``).  
+pass any argument except for the ``--host`` option (which is always set to ``0.0.0.0``).
 E.g., to find and use a free port, use:
 
 .. code:: sh

docs/dev/index.rst

@@ -6,6 +6,7 @@ Developer documentation
    :maxdepth: 2
 
    quickstart
+   commits
    rtm_asdf
    contribution_guide
    extended_types