Is Your Git Repo Communicative?

I saw a few tips on LinkedIn regarding good habits for git commits. It made me wonder about how my team and other teams in my organization use git and if they use it to communicate effectively.

One thing I noticed for the repositories at my organization, there was a loose relationship between how many people maintained the repo versus the quality of the git messages. That makes sense: if you're the only maintainer on a project, it can seem like you're talking to yourself. Why write an elaborate git message for yourself?

When maintaining a code repo by yourself, being disciplined about how you commit code is not only helpful for your future work with a team, it can help your future self not have to think so hard. Consider scenarios where you may need to look at your previous commit messages or pull requests and help yourself remember key details and make good decisions quickly.

So, how does one know if they're good at managing source code? I did a bit of searching online and one of the articles I looked at referenced how git is used with the Linux kernel. The post is very long, but it is full of interesting conventions for the people that maintain the Linux kernel. Surely, the person that created git has the best practices for using git all figured out!

The kernel.org post does have interesting conventions in it, but some of them likely won't make sense for a repo controlled privately by a single company. For example, the post indicates (at line 102) that when submitting a pull request to a maintainer, be sure to be clear about what problem you are solving, not just what you changed. Based on this direction, we can tell that git is used for much more than just managing code at kernel.org. A Linux subsystem maintainer may get pull requests from people they don't know for fixes or features they didn't ask for.

If you're working at a company and submitting a pull request to an internal repo, you've likely been told what the problem is by a product owner, scrum master, lead developer, or manager. You don't need to convince anyone that this pull request is needed; they're likely expecting it.

If your pull request is expected, there is likely a ticketing system of some kind being used. So, you could just reference a ticket number with your commits and/or pull request. Referencing a ticket number isn't a bad idea, but ONLY referencing a ticket number could be. Unless your source control and ticket system are well-integrated, you can end up with a list of commits that are just numbers. Not very useful when you're looking back through changes.

Is there a standard way to do source control? Yes, but only if YOU make one. Consider your team's size, your team's roles, your team's work methodology, the branching strategy used, the tooling your team has access to, etc. Based on all these variables, what makes sense for your team?

It would be an excellent idea to meet with your team, iron out the details, and then document the standard on a wiki or shared document. Then, when the next developer joins the team, they can learn the standard immediately and not disrupt the team's code handling processes. Your manager should thank you for it!