Estándares GIT

Owned by Eduardo Martinez (Unlicensed)
Oct 27, 2022
7 min read

 

Overview

This are the git conventions to follow to keep a clean history, track easily the code related to a story and have an standard branching process.

Dictionary

TYPE: identifies the type of the ticket this commit is related:

  • feature: Any code changes for a new module or use case should be done on a feature branch.

  • bugfix: If the code changes made from the feature branch were rejected after a release, sprint or demo, any necessary fixes after that should be done on the bugfix branch.

  • hotfix: If there is a need to fix a blocker, do a temporary patch, apply a critical framework or configuration change that should be handled immediately, it should be created as a Hotfix.

  • docs: Changes that only affect documentation files.

  • revert: Revert a previous commit.

TICKET-ID: Jira Ticket Id.

Example: POP-1234

SHORT-DESCRIPTION: Jira ticket title

TICKET-LINK: Jira ticket link url.

DESCRIPTION: List of changes in or activities done in this ticket.

Branching convention

When you start working in a new ticket you need to create branch with the following rules

TYPE/TICKET-ID

In case there is no existing ticket related to the change a new ticket must be created in jira.

Command
git checkout -b type/ticket-id

Message convention

When your changes are ready to be commited in your working branch you need to use the following convention:

type(scope): subject newline ticket-link newline body newline

In case this commit includes more than one ticket the tickets will be separated by an space and all links will be included.

 

type(scope1,scope2,scope3): subject newline ticket-link1 ticket-link2 ticket-link3 newline body newline

Example:

Commit message Intellij Plugin

To create your commits in an easier way you can download the plugin Git commit Message Helper.

https://plugins.jetbrains.com/plugin/13477-git-commit-message-helper/

Configuration

Go to intellij Preferences → Other Settings → GitCommitMessageHelper

Configure the types we are going to use.

Then click on template tab and use copy this template.

Usage

When you changes and ready and you are going to commit open the Commit changes window (Ctrl + k or Command + k).

Click on the following icon.

A small window will open and you can populate all the fields as the following example.

 

CLI Fan? I got you covered

If for some reason you need to commit your changes using your command line interface you can use this template as reminder of this configuration

Just save it as .gitmessage in your local folder, and then execute the next command to store it as template:

git config --global commit.template ~/.gitmessage

VALIDATION

To install the validator tool run:

 

The project will use commit liint and husky to validate the commit message integrity.

Each time a commit is made, husky will validate the integrity and print the rules that were broken.

 

PULL REQUEST

When you create a pull request you need to include some reviewers before merge to master, this reviewers will provide some feedback in you changes until the code is acceptable and follows the best practices.

To keep a clean history in git log we need to follow some rules before merge to master.

Rebase, Squash, Merge.

Rebase

The rebase operation will help us to integrate our new commit at the end of our git nodes.

Lets use this example.

As you can see the branch feature/EXAMPLE-1234 was created from “common node” but master is already 3 commits ahead. if we just merge our branch to master we will create Merge commit and that dirties our history.

To solve this we are going to use the rebase command, make sure tu run a pull first, so you have the latest history log on master.

First we are going to go to our branch.

Then we are going to run the rebase

you are going to see how our new commits are directly linked to the last node in master

Then we can push this branch

Squash with command line

Squash means to take several commits and just make one, this will help us to have our history clean and encapsulate on functionality in one commit.

To Squash we will start understanding how many commits we want to squash.

We use this command to start the squash depending on the numbers of commits to squash,we will use 2 for this example

This will open a VI with the eligible commits

 

On the commit we want to squash we will change pick for squash.

then we save and exit VI.

This will sent us to other screen where we can customize the message of the new commit.

Finally we can push with --force-with-lease.

Optional:

Squash and Merge

To keep our history clean when we are ready to merge the commit to master, we are going to squash all of our commits to only one commit. This commit will include al the changes made for this specific story, which is going to help us to navigate on our history in an easier way.

To do the Squash we can use github tool to do it, or we can do it with command line using different techniques. Here is the link to one of those techniques.

https://levelup.gitconnected.com/how-to-squash-git-commits-9a095c1bc1fc

When we click Squash and merge github is going to allow us modify the commit message. Here is where you need to be pretty careful to follow the commit message convention previously described. And only include once the link and the list of changes.

Finally we delete the branch that was merged and we will have our changes in master with a clean commit message.

 

GIT PROCESS FOR BUGFIXES AND HOTFIXES

The way we handle the sprint development and different environments is the next way.

master → Current Sprint → All the code developed in the current sprint will be joined in master branch witch automatically will deploy to dev environment. Here is were all the developers will test their code and integrate with other teams as front end, or POS.

qa → Previous Sprint → All the code developed in the previous Sprint will be deployed to qa branch once the sprint is finished and the code in qa was already promoted and saved in staging branch. Here is were qa amd PO will test the features developed in the previous sprint. If there is any bugfix that needs to be merged to qa to solve some rework. The process will be:

  • Create a new branch from qa HEAD.

  • Push the fixes in that branch.

  • Make a pull request from your branch to qa.

  • Make a pull request from your branch to master or ask some one with github higher permission to make a cherry pick from your commit from qa to master.

prod → 2 Sprints Behind → All the code developed in the 2 Sprints behind will be deployed to prod branch once the qa cycle is finished and all the action items for production release where completed.

If there is any hotfix that needs to be merged to prod to solve some high priority issue. The process will be:

  • Create a new branch from prod HEAD.

  • Push the fixes in that branch.

  • Make a pull request from your branch to prod. (if you need to test the change before, make the first PR to master or qa)

  • Make a pull request from your branch to qa or ask some one with github higher permission to make a cherry pick from your commit from prod to qa.

  • Make a pull request from your branch to master or ask some one with github higher permission to make a cherry pick from your commit from prod to master.

The high level of this process where QA team and PMs are involved will be as showed in the following image:

DEV team will be delivering tickets of Sprint X-1 that will be tested by QA team and signed off by PMs in Sprint X, meaning a process of development and QA of 1 month to complete the respective tickets. In other words, one sprint is needed for development and the next sprint testing is applied.