first commit

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