Git Commit and GitHub Best Practices

The first rule about Git best practices that we always hear about is making lots and lots of commits frequently. While this is mostly true, we should also keep in mind that Git commits are also a form of code documentation and we should try our best to communicate the intent of our changes. So basically remember to commit frequent to save your work, but once you’re ready, spend a minute or two to share your brilliant code with the rest of your team by writing good commit messages.

To set up a default git message template, go ahead and edit your config at  ~/.gitconfig and add the following line. Of course you may choose any other naming convention for this file.

Now that we’ve set up where Git should look at our git message template, let’s go ahead and edit  ~/.gitmessage  with our custom default message.

I use Jira in my organization, so including the story number in the subject line helps with the integration on our Jira board. Naming is optional although recommended if you work in a large organization as it’s easier for other engineers to address you by your name instead of your GitHub user name.

GitHub automatically generates task list in the Pull Request based on the commit message template that I’ve created here. This is useful for several reasons. First, it reminds the writer that they may need to review the code again for cleanliness and perhaps to retest any logic that he may have missed in the initial commit. Secondly, it also serves as a checklist for code reviewers to quickly glance through code reviews that have yet to fulfil all these criteria before they start reviewing your PRs. Message templates are certainly a great way to train us to be better, more disciplined engineers.

I always encourage my team to include screenshots or even animations to illustrate the changes that they are making if they involve any UI/UX changes. Screenshots greatly improves the code reviewer’s understanding of the changes being made visually and also serves to annotate changes in UX interactions that may be difficult to describe in words. This can also be in a form of before and after screenshots. Seeing these changes also provides a context for the code reviewer to quickly identify if a particular change in UI may affect other parts of the system or perhaps in mobile responsive views. I use a combination of Skitch from Evernote which is free and Giphy Capture for screen recording. I’ve also listed similar alternatives for the Windows platform below.

Mac

Skitch

Giphy Capture

Windows:

Sniping Tool – Available since Windows Vista

ScreenToGif