Storytelling with Git
I know, I borrowed the term from storytelling (which is a whole different subject) so I can catch your attention. Storytelling is a way of putting your thoughts in an organized way so some can follow them and understand the message you are trying to convey.
An important definition of communication: communication is not what you are saying, is what others are understanding!
This leads to an important question: which message are you trying to convey with Git?
Can someone read your git log and understand the way the code was developed? Check out this classic xkcd about the subject and reflect about your git commits — no judgment there :).
So, how can we improve our methodology so we save ourselves from doing that? There are important methods that can help: branching models and conventional commit format. The first defines branching names formats (syntax) and the meaning of every branch we defined (semantic). The second is about the commit message itself and what kind of information and details you outline on it.
Branching Models
We can see the branches as chapters in our novel, and, like any kind of literature, chapters are organized in a given way particular to the message being transmitted (romances are totally different from Ph.D. thesis for example).
I’m going to list some branching models so you can check them further. I will not dig into explaining each one because there is already a lot of very good material on this matter.
Git Flow
Git flow describes a branching format with development, features, long-lived features, release, and hotfixes branches. The idea is to “progress” from feature branches until releases, with the hotfixes exceptions. This post by Vincent Driessen is amazing and describes this in detail:
Besides using the concepts, you can also use the gitflow extension (https://github.com/nvie/gitflow) which will make your life easier. This tutorial also can help you out:
A variant of Git Flow is the Gitlab flow, which removes some components of Git Flow and makes it more dynamic. It is also aimed to be used together with the issues, merge requests, and pipeline features that Gitlab provides. An excellent set of features must I admit!
You will find that all the most used SCM (Github, Bitbucket, Gitlab) will allow you to set up all those flows and tweak them for details you need. Just remember, nothing is written in stone and the processes may (or should) change, so don’t feel bad if you need to adapt your process after a couple of interactions — a tip, start in a small scope, like a team full of early adopters, they will love to tweak the process :).
Another particular experience: it's easy to start using a subset of a branching model and later start using the branches as they are needed. For example, a small team can have a single development and production branch, but release branches make no sense in this case. In other cases, hotfixes also make no sense if you always pushing development forward as fast as you can. Therefore remove — or just don’t use — the things you need from the branching model and don’t use them until you need them, but rely on the branching model for having them at hand when you need them.
Conventional commits
Branching models will shape the chapters of our history. But and about paragraphs? We can map them to commits. Each commit will describe an action. Eventually, more than one commit will describe the same action with different points of view: implementation, documentation, automated tests, etc.
But the question is: how we make sure we don’t fall into the temptation of writing the “haaannnndddsss” just like the XKCD comic? We adopt a standard. I won’t jump in the standard, it can be as easy as “describe what the commit does, having a verb and a noun” or having commit categories and etc like this convention. Just adopt one and stick to it — until you decide on a new one.
Conclusion
In the end, more than conventions, what matters is understanding. You must see Git as a way of documenting your steps to modify a system. It's not a backup tool, it’s a source code management tool, I think you see the management there. Management of past, current, and future source code. So next time you commit or start a project, take all of this into consideration!
