Git

Default branch

We’re using main as default branch.

Important

All projects using main as default branch have to be migrated to main.

Merge requests

Pushing to the main branch is not allowed. Instead we do this:

  • Create a feature branch for your changes

  • Open a Gitlab Merge Request to merge your branch into main

  • Make sure your feature branch is rebased to main before opening the merge request

Important

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

Fast-forward

We’re enforcing fast-forward (i.e. via GitLab Guard) because of the following reasons:

  1. The Git history becomes linear, and looks much nicer

  2. A linear Git history is easier to debug

  3. Enforcing fast-forward before the merge, will result in having all changes before the merge

  4. It also means “merged” tests are running before the merge

  5. This results in a much more stable main branch

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

  • main 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 main

  • 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 main 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 (non-annotated) tag on the tip of the release branch

  4. Merge the release branch back into main

  5. Delete the release branch

Hint

You can also define the new tag directly on main, instead of going via release/* branch. However, this requires more coordination, since you can’t “freeze” main.

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 main 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

  • CI: 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 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 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 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 highlight word in the commit message.

Validate commits CI file

Most projects will check the commit messages via the validate-commits CI file of the Shared GitLab CI files.

Hint

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

Further subtopics