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
|