The perfect Gitflow
How to optimise your workflow with GitLab
Introduction
The method “Gitflow” is commonly known throughout the coding community. I would dare to say that most developers nowadays work with it on a daily basis —just like us. Even though the branch naming and merging conventions are easy enough to memorize, while working with Git(Lab), you will have to make decisions about certain things. In this article I am going to talk a little about which decisions we took and why.
At Ambient Innovation we are using GitLab— but most of the following topics should be transferable to Github.
One merge request, please!
If you want to transfer one branch into another, it is wise to do this via a “merge request” (MR). This prevents making mistakes when merging manually but furthermore creates the opportunity to run automated quality assurance. You could set up a continuous integration pipeline (CI) to lint and unit-test the code. In addition, a merge request is a great tool for manual code review. In most of the IT companies I know, this is a compulsory step in the development process — and that is a good thing because often bugs, ugly parts of code or overlooked edge cases are discovered this way.
It all starts with branching…
The concept mentioned above is simple to implement, nevertheless you have some degrees of freedom when creating an MR. We use GitLabs Kanban board integrated in “GitLab Issues” to keep track of our tasks and tickets. This is pretty neat as it automatically creates links between the code and related tickets. For example, if you put the ticket id with a leading hashtag in the title field of a merge request, GitLab shows all related merge requests within the ticket (to be seen the image below) but also you will see a link to the ticket in the title of the MR.
In the following image, you can see that all related merge requests to ticket #178 are already merged and done.
GitLab detects when you push the first commit to a new branch. It will display the option to open a merge request and the branch title will be adjusted automatically. If your branch name contains the ticket id with a leading hashtag, the link between the MR and the ticket will automatically be set. Therefore, I’m a fan of naming branches in the following way because it can prevent manual mistakes:
feature/#27-my-awesome-feature
WIP or not WIP — that is the question
You can mark and unmark a MR as “Work in progress” (WIP) via a convenient button below the title field:
Labelling all your WIP-requests as such does not only give you a better overview but also avoids an accidental merge via the GUI.
Sometimes people will mark a request which is awaiting a review with a “REVIEW” prefix. Personally, I can’t recommend people to do this, because by definition everything that is not “WIP” is ready. Why make an additional effort and add a potential source of error?
Update: In the most recent version of Gitlab, “WIP” was replaced by “Draft”.
I like to configure stuff
In addition to the points stated above you can customise two settings when creating a merge request. “Delete source branch when merge request is accepted.“ and “Squash commits when merge request is accepted.“
Deleting the source branch after merging is a good choice in most cases. If you keep the branch the developer needs to clean up later manually which is prone to be forgotten and usually ends in a mess with a huge number of stale branches. At this point it will be close to impossible to find out which branches still contain relevant changes.
Fortunately, you can set this to be active by default in the projects settings:
Settings → General → Merge requests → “Enable ‘Delete source branch’ option by default“
Lately I have become a fan of squashing commits on a merge under the condition that you worked alone on that particular branch and that nobody branched off it. Squashing means that all changes will be put in a single commit in the target branch. The drawback is obvious: All of the history and all commit messages will vanish. This is specifically a shame if somebody put lots of thought into when to commit and wrote extensive commit messages. On the other hand only finalised features or bugfixes end up in the dev or master branch. Should a problem occur after a merge then it’s easy to find the commit causing the trouble because the history is clean. Moreover, most developers tend to write — let’s put it this way — reduced commit messages. So there’s just a slight benefit of keeping all of those messages.
Therefore, one single commit which contains all the changes and maybe has a proper commit message (after all, you just have to write one at the point when you are done) seems to me to be the greater benefit.
TL;DR
- Use Merge Requests (MR)
- Use the “WIP”-prefix in merge request titles
- Put the ticket id with leading hashtag in the branch name („feature/#27-my-awesome-feature“)
- Put the ticket id with leading hashtag in the merge request title
- Activate “Delete source branch“ in the project settings
- Use “Squash commits“ if nobody else branches off the according branch and you alone worked on it
