Git
===

Git workflow
------------

We're using the following Git workflow:

.. image:: /_static/git_workflow.svg 

.. hint::

    Please read the next chapters to get more details on our workflow.

Merge requests
--------------

Pushing to the ``master`` branch is not allowed. Instead of it do the following:

- Create feature branches for your changes.
- Open a `Gitlab Merge Request <https://docs.gitlab.com/ce/user/project/merge_requests/creating_merge_requests.html>`_ to merge your branch into ``master``.
- Make sure your feature branch is rebased to ``master`` before opening the merge request.

.. important::

    Protect the ``master`` branch so that pushes are **not allowed**. Also make sure merge requests are **fast-forwarded**.

Branches
--------

The branch name should **briefly describe the contained changes** and/or what it's trying to achieve. 
However, there are some restricted branch names, i.e.:

- ``master`` is our main branch (bleeding edge, latest greatest, and so on)
- ``release-*`` is a freezed release branch, which is used for tagging & merged back into ``master``
- ``hotfix-*`` is a hotfix branch, which fixes something on the current productive version

.. hint::

    In case you've a Gitlab issue, you can **simply create a new branch by clicking on a button in the issue**. This way, the branch is linked to the issue.

.. important::

    The ``master`` branch is the **only eternal branch**. All other branches, such as feature, release & hotfix branches are ephemeral.

Versioning / tags
-----------------

Version
~~~~~~~

We're using the versioning format ``{MAJOR}.{MINOR}.{FIX}``.
This results in the following naming conventions:

- **Tags**: ``{MAJOR}.{MINOR}.{FIX}``
- **Release branches**: ``release-{MAJOR}.{MINOR}``

Tagging
~~~~~~~

Tagging happens usually like this:

1. **Create a new release branch** to freeze it from latest changes
2. Test it and **fix whatever you need**
3. Create a new **annotated tag** on the tip of the release branch
4. **Merge** the release branch back into ``master``
5. **Delete** the release branch

.. hint::

    You can also define the new tag directly on ``master``, instead of going via ``release-*`` branch.
    However, this requires more coordination, since you can't "freeze" ``master``.

Productive version
~~~~~~~~~~~~~~~~~~

There's no branch (such as in Gitflow) which describes productive (rock solid) releases. Instead of it, the productive version is always the latest tag.

.. important::

    If no versioning is required, then tags & release branches can be skipped. This means, the tip of ``master`` will then be the productive version.

Commit messages
---------------

Prefix
~~~~~~

Make sure you **prefix** your commit messages with one of the following prefixes:
 
- ``FEATURE: Add new SPAM feature``
- ``FIX: Fix the annoying SPAM bug``
- ``REFACTOR: Refactor code of SPAM`` (*code is changed, isn't styling only*)
- ``STYLE: Remove superfluous spaces from SPAM`` (*code is not affected, only styling*)
- ``CLEANUP: Remove unused imports from SPAM``
- ``DOC: Update the documentation of SPAM``
- ``TEST: Add new CI test for SPAM``
- ``BUILD: Exclude SPAM from package build``
- ``PIPELINE: Update CI/CD pipeline to deploy SPAM``
- ``MISC: Add SPAM to .gitignore``
- ``REVERT: Revert the SPAM commit``

.. hint::

    All allowed prefixes can be found in :data:`confirm.tools.git.PREFIXES`.

Summary
~~~~~~~

Please follow these rules for a good subject:

- Limit the **summary** (aka subject) to **50 characters**
- **Capitalize** the sentence
- Do not end the sentence with a **period**, as it's unnecessary
- Use the **imperative** mood

.. hint::

    Using imperative mood can be tricky at first. Just remember these rules:

    - Write the subject as if it's a **command or instruction**
    - The subject must be able to complete the sentence "**This commit will…**"

.. important::

    We're automatically generating the :ref:`tools:Git Changelog` from Git commit messages.

    Always use **proper commit messages**. Commit messages must be meaningful and short at the same time. Things like ``Changed some files``, ``Update`` or ``Fix`` are not proper commit messages and you'll burn in hell for it! 

    Also ensure you don't use identical summaries for multiple commits. You might want to squash them instead.

Description
~~~~~~~~~~~

Please follow these rules for a good description:

- Wrap the description (aka body) at **72 characters**
- Use it to describe the **what** and **why**
- Do not describe the **how**, as this describes the changeset itself
- Clearly mention any **related issue** numbers with the GitLab syntax (i.e. ``#…``)

.. important::

    We're automatically generating the :ref:`tools:Git Changelog` from Git commit messages.

    Some commits don't need a description and might be fine with only a summary line.
    However, if a commit (message) requires **special attention**, make sure you're using a 
    :data:`highlight word <confirm.tools.git.HIGHLIGHT_WORDS>` in the commit message.

Validate commits CI file
~~~~~~~~~~~~~~~~~~~~~~~~

Most projects will check the commit messages via the `validate-commits CI file <https://git.confirm.ch/confirm/gitlab-ci/-/tree/master/validate-commits>`_ of the :ref:`Shared GitLab CI files`.

.. hint::

    The ``Validate Commits`` CI job will use the :ref:`tools:git-tools`, respectively the :ref:`tools:Validate Commits` action.