Improving use of the repository

Lucas Pelizza
Jul 30 · 4 min read

I’m going to share some tips that helped the entire team improve the use of our Gitflow repository. This is not a guide to using Gitflow — if you want to review the concepts you can enter to Atlassian Gitflow.

Commits — Small Details, Deep Impact

With small changes in the work done day by day, significant improvements can be achieved for the whole team.

Commit messages are something we write all the time every day. If we pay attention to the commit message, we can significantly improve the understanding of the changes that were made. However, if we do not focus on the message of the commit, tomorrow the whole team may have drawbacks for those commits that are illegible, insignificant, useless.

Example of useless commits

Tips to improve commit messages:

  • Define a commit message template across team members. This will improve the quality because the entire team will be familiar with the commit message struct. Then, they will understand what a commit does with a glance.
  • Define commit message types like Feature, Bug-Fix, Chore, Hotfix, Document, etc.
  • Include meta-data, which helps to find more information about the change: issue tracking IDs, tickets link, pull request numbers.

Following the previous for a while, I’ve been using this template:

[App Version] [Type of commit]: [Description] — [Ticket URL]

Using this template my repository has changed a great deal— it is now more readable and the commit messages are significant for every teammate who reads the history.

The word link represents the place where the task’s link should be

Naming Branches

After a while using Gitflow, we found a large number of branches. Many daily actions began to be difficult to perform, like:

  • Knowing which version of the app will impact the changes found in a particular branch and when we need to change branches.
  • Visualizing, at a glance, the features that are included in a certain version of the app.
  • Finding the branch that has the problem quickly in case of failure.
Branches without template name

If we apply a small change at the time of creating the branch we can solve all the above-mentioned problems, and add some benefits.

At the time of the creation of the branch, we can use a template similar to the one mentioned in the commits section:[Type]/[App version].[Description]

Branches using the template name

With this simple change, we’ve managed to have a branch structure with several benefits. Some of these benefits are:

  • Branches are sorted by App Version
  • They’re very readable
  • The branches are grouped by App Version
  • Easy way to know with which App Version the change is related

Use Squash

We all know that a repository becomes increasingly difficult to understand when the team gets bigger or/and as time goes by. Every time we have more branches, more commits, and all end up being included in the Develop branch.

When merging a feature branch into develop, all the commits of the feature branch will be taken into develop. That causes a verbose log containing a lot of messages, that, feature-wise or bug-fix-wise, would be highly confusing. See this for example:

Branch history using just merge

In order to avoid such a messy commit history, we would ideally merge a feature branch and see only one commit. That commit should have the feature name and an explanation of what it comprises. To achieve this, we can use squash.

For example: if we use Bitbucket at the time of making the merge, we select the option “Squash” instead of “Merge” and add a title following a template. In my case, I use the template:

[App Version] [Type of commit]: [Description] — [Task’s Link]

Squash using Bitbucket

This simple change gives us a series of benefits:

  • The commit descriptions in the Develop branch will be your Changelog when it is merged to Master.
  • It’s very readable
  • You always have a link at hand to see the reasons for the change
  • Easy way to realize in which order the features, bug fixes, chore are merged. This can help a lot if you are unsure which feature breaks something else in your project.
Branch history using squash

Final Words

I hope that this article helps you to have more efficient and accurate teamwork.

If you have a similar or different workflow that works for your team, I would be pleased to hear about it.

Better Programming

Advice for programmers.

Thanks to Leandro Pérez

Lucas Pelizza

Written by

iOS Engineer. #Swift fanboy

Better Programming

Advice for programmers.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade