Sanctity of Git Repository
The term “There’s only one truth” is good on ears however very hard to define in practical world. However you all ( ok ok … I get that… I mean at least all developers ) will agree that GitHub will be that place where you will search for that one truth.
I started my version control journey with VCS(https://en.wikipedia.org/wiki/Concurrent_Versions_System), since then I have moved from Subversion, AccuRev, Perforce, IBM RTC and finally looks like I have settled on git from 2016.
In these years I have came across numerous repositories, some of which are very well managed and some not so.
Here is the list of things delights me when I see them in repository,
- Keeping it clean
I have see repository with 255 branches, which is a outrageous number. It confuses new team members to comprehend code — what is important vs what is not.
With passing days these un-merged branches becomes even more difficult to delete as we tend to forget what is in there.
The one rule I follow is to delete the branch promptly after PR is merged.
2. Unmerged branches
In some repo you see the branches are quite deviating from each other, some are not merged with master for long time ( weeks and months ) — which makes me wonder if we ever going to merge them.
Base minimum the branch can be atleast kept up to date with master.
3. Use tags and release
I have seen services which are in production for more than couple years with 0 tags and 0 releases. If you are unsure of what is the different between tag and release check here (https://stackoverflow.com/questions/18506508/whats-the-difference-between-tag-and-release)
Tags and release are excellent feature to mark a point in history of codebase with additional documentation. It also helps the new people on team to understand the code milestones.
Many CI-CD tools also supports creating release\tag automatically which I think is the excellent feature.
4. Goody goody Code review comments
Code review is not the place where you want to be nice with each other. I would give and would like to receive a candid feedback. I think ultimate nirvana for programmer is to detach personally from their code, and code review can be a good opportunity to practice that sense of detachment.
Comments like “Looks good to me” serves no purpose. It is the matter of maintaining that one truth and candid feedback help good programmer to be a great programmers.
As it is often said feedback is the gift and it is shame to miss this opportunity.
5. Don’t turn world upside down with single commit or pr
Many times, team members who are new to the code base use commit history as a way to understand the evolution of code. And, I found that it is extremely helpful technique.
Try to split your changes into multiple commit’s for example while refactoring never rename the files and update it in single commit.
Be careful with using “Squash and merge” which eats up all the history.
6. Petty commits
On the other extreme I have also seen repositories with very large number of commits with comments like “update1”. For branches with such commit’s “s quash and merge” is the best option which consolidate multiple merges into single commit to upstream branch.
7. Not enough readme
Nothing goes stale quicker than the Readme in GitHub repo. Many of the times readme is a first thing which gets created. At the minimum readme should have section on “Setting up development environment” and links to other important artifacts.
I am sure there are lots of other tips and ways to maintain the “Sanctity of Git Repository” however I will stop here to keep this article small.
Please let me know your thoughts and comments.
I greatly controlled my urge to title this post as “7 habits of clean repo” :)
