Git#

Git workflow#

We’re using the following Git workflow:

../_images/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 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 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.