searxng/docs/dev/commits.rst

.. _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