Alexandre M. Savio

Alexandre M. Savio

Published

Thu 11 June 2020

←Home

Git usage guidelines for team collaboration

// under git collaboration team

Introduction

This is a set of rules that I have been gathering in the past few years which work well for most of the projects I worked on with small teams of 3-8 people. These guidelines are heavily based on the angular.js/DEVELOPERS.md document on GitHub and this is not about GitFlow.

Branching model

Always create a new branch from an up-to-date “main” branch. The branches should have a short life (no more than 2 days) and have a very determined objective. Once the objective is reached, a Pull Request (PR) should be created to merge the branch to main. Once the branch is merged, it should be deleted. Always merge to main.

Branch names

The branch names are not that important in very small teams, but when the team is bigger or work remotely, a pattern for the branch names is also good to follow. Here is a suggestion:

```
<type>/[<ticket_id>]_<subject>
```

Some tools like Sourcetree pick the / from the branch name and splits the name in their GUI, so you can see the different types of branches as in different folders.

Type

The describes the generic objective of the branch, it can be one of the following:

  • feat: a new feature,
  • fix: a bug fix,
  • docs: documentation only changes (in or out of the code),
  • tests: new tests or fixes in tests,
  • refactor: code change that neither fixes a bug or adds a feature,
  • style: code changes that neither,
  • chore: Changes to the build process or auxiliary tools for the project maintenance,
  • perf: A code change that improves performance.

Ticket ID

This is optional, but is good if the purpose of the branch is too complex or if you follow a Scrum development process. The should be the identifier of the ticket or user story that the branch is going to solve. The format depends on the project management tool you are using, but usually it has a project acronym and a number: PRJ_123.

Subject

The part should be no more than 3 or 4 words about the specific objective of the branch. If you don’t put a ticket ID, the specificity of the name is more relevant.

Commit messages

Here we follow a very specific pattern in order to be able to parse the commit messages to automatically generate a change log for each release in a CI/CD process and also semantic release version bumps with tools like semantic-release (available for Node.js and Python).

Format

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

```
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
```

The header is mandatory and the scope of the header is optional. Any line of the commit message cannot be longer 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Type

The describes the generic objective of the commit, use the same types used for branches. I will repeat them here:

  • feat: a new feature,
  • fix: a bug fix,
  • docs: documentation only changes (in or out of the code),
  • tests: new tests or fixes in tests,
  • refactor: code change that neither fixes a bug or adds a feature,
  • style: code changes that neither,
  • chore: Changes to the build process or auxiliary tools for the project maintenance,
  • perf: A code change that improves performance.
Scope

The could be anything specifying place of the commit change. A scope should be a part of the project that the stakeholders understand. The possible scopes can be agreed beforehand with the developers and/or stakeholders. You can use * when the change affects more than a single scope, but you can also not put anything (remove the parentheses as well).

Subject

The contains succinct description of the change:

  • use the imperative, present tense: “change” not “changed” nor “changes”
  • don’t capitalize first letter
  • no dot (.) at the end

Don’t use generic subjects as: ‘debug’ or ‘few fixes’. Be clear and specific.

Body

The is optional, but if you use it, just as in the subject, use the imperative, present tense: “change” not “changed” nor “changes”. The body should include the motivation for the change and contrast this with the previous behavior.

Footer

The