Git culture

By Sergey Gernyak, RoR developer at WeAreBrain

So here are my thoughts regarding Git culture which my teammates and I try to follow during each development process. It doesn’t outline anything new or innovative, but I think it’s very necessary to have a general guide to refer to while you’re knee-deep in the development process. So, here we go!

Github flow

Github flow overview

We try to use Github flow for all our projects. I won’t cover all of the concepts of this flow, so please use the link to the original source with all the information. I want to start by listing some important items to consider before going all in:

• Your master branch should always have a stable version of the application
• You should never merge untested code into your master branch
• The feature branch is short-lived, so after you’ve finished a feature, the relative branch should be removed to keep the repository clean

JIRA and Bitbucket

We use Bitbucket to keep our code in one place and we use JIRA as a ticket service to assist us with planning and scheduling. These two services can be integrated together and you can control your tickets via the commit messages. Later I will describe what I prefer to use and what I don’t.

Branches

In Github flow the only one long live branch is master. The other ones are feature branches and should be deleted right after you merge them into the master branch. The name of the feature branch should reflect its purpose and what this branch provides (i.e. what feature carries). Very often I see a branch named like a feature (PRJ-001) and that’s it. Connection between bitbucket and Jira makes some references for you, but when you visit Bitbucket and observe a list of available branches, such ones do not say anything for you. For feature branches I prefer the following pattern: feature/PRJ-001-the-short-name-of-the-feature. Usually I don’t remember a number of an issue, especially when you have more than several thousand of them, but I know the name of the feature. So, it will be very handy for other guys to not search Jira to find a number of a story to know what branch they should pull to continue to work with.

Commits

This is a most interesting and most annoying topics for me. A lot of developers think (sometimes I do the same) that commit messages aren’t worth thinking a lot about and just put there several first appeared in the mind words. I think in the hit-parade of the most often used words the first place takes fix . The sad thing that the commit message could be represented only by that single word.

Considering my experience about commit messages, the second place takes the number of the issue with some narrative message included. For example, PRJ-001 or PRJ-001: some minor changes. In my opinion, the number of the issue does not say anything when you’re trying to find a needed commit in the Bitbucket. The other problem is putting the number in the first line of the commit message — it uses a lot of characters from the visibly limited first line, but the value of it for the reader is zero.

Connection between Jira and Bitbucket is very handy in some cases, but I can’t remember at least one instance when I needed to find a commit by an issue number. I don’t want to say that you shouldn’t use it, but we can adjust its usage a little bit to make commit messages more user and developer friendly.

The goal of what a commit message should reflect

I’ve tried to specify some rules for commit messages and put them as a git hook, which will check messages during the commit creation flow. There is a repo with it. Please visit the repo page for a more detailed descriptions of the rules. I will only specify these important notes:

• Main line MUST NOT contain an issue number
• Main line length MUST NOT have more than 50 characters. Additional lines MUST have the issue number OR [no-issue] label
• Additional lines MUST have a more detailed description about what this commit carries

PLEASE NOTE: Commit message aren’t limited to only one line. Actually, only the first line is limited to 50 characters but you can add more lines below. Generally the pattern looks like the following:

My very useful commit with a lot of changes

[PRJ-001]

The very detailed commit description. What the reasons of this commit are, or what exactly this commit changes, or what breaking changes are, or however you want to outline it to notify your team:

- point 1

- point 2

- …

Please notice about two blank lines after the first one and after the one with an issue number.

A very good example of a commit message is:

Good example of a commit message

PLEASE NOTE: No one really thinks a lot about commit messages until they need to find some special commit in the vast commit history — so correct labeling and referencing is important.

Pull requests

Let me clear some things up first:

• They aren’t about wasting valuable development time
• They aren’t about fooling you
• They aren’t about saying that all your code is shit

These are some of the common misconceptions about pull requests. I was very confused when I first heard someone say, “Make commits directly to the developer. We trust you. And I am tired to review pull requests right now…”. The goal of pull requests is so much more than that. And it’s wrong to think that you can simply integrate PR into the development cycle once and all will go smoothly. No, that’s not enough. It is a vital part of the engineering culture and each person in the team should to follow it. And what I saw in my team’s experience is that doing pull requests do not automatically imply that you do a code review. A lot of times I see some developers not having time to review changes and simply take for granted that the changes are correct. Ahhhh…. 😢

The goals of pull requests are:

• To share knowledge with your team about which feature you were working on and how you’ve implemented it;
• To hear opinions from other team members, it is important to talk about a feature even during its active development process;
• PR is a context of the feature, which you want to integrate into the main development branch, so, you can open a list of PRs and see on a high level what features your team added into the project so you don’t have to sift through numerous commits.

I prefer to not put off PR creation time. Basically, I create PR right after I’ve made a first commit into the feature branch. By doing this, I let my team see my changes and allow them to add questions, comments or remarks so we are all on the same page. In an ideal situation, after I complete a feature the final review process will go quickly due to everyone in the team being aware of the feature realization approach and I’ve already fixed all of their comments and suggestions and all of the inconsistencies/bugs/etc.

Conclusions

Try to think about git history as a story of how your project evolves, step-by-step. It has been started from the Initial commit and now you’ve added some very sophisticated business logic inside it. And you should remember an order and titles of the features using the commit messages for that. Try to read what you’ve done on your real project, for example, during the last month. Can you easily do that?