750a7b4d6f
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>
109 lines
4.1 KiB
ReStructuredText
109 lines
4.1 KiB
ReStructuredText
.. _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
|