Useful Commit Messages

[00:00:00]
>> Nina Zakharenko: Let's move on to the next section. We're gonna talk about history index. We have all seen a commit message that looks something like that. I love xkcds, so you guys get more comics. [LAUGH] Your commit messages might start out strong. And eventually, they just end up saying things like more code, or here, have code.

[00:00:24]
>> Nina Zakharenko: This isn't great, and we've all tried to debug something and we come across a commit message, and all it says is fix bug, and you're like, what bug? I'm trying to track it down, I'm trying to troubleshoot whoever committed this code change, has just completely screwed me over, at this point.

[00:00:45]
It makes us want to just curse the person who did that, maybe stick some voodoo pins at them, plot your revenge. All it would take is a few extra descriptive words, and it could have saved us hours of work. And the effect of bad commit messages, really ended up compounding over the lifetime of a project.

[00:01:09]
I like to think of it, kind of as the broken windows theory. If you commit with bad commit messages, then other developers will think that's okay.
>> Nina Zakharenko: Good commits are really, really important. They preserve the history of a code base. They can help you with debugging, troubleshooting, if you need to create release notes, if you wanna know what went into version 2.0 of your project, you can pull up your commits and answer that question easily, if your commit messages are good.

[00:01:40]
It helps with code reviews. If I'm code reviewing large poll request, I'll actually go through and look at the diffs of each individual commit, so that I can see how the code had changed over time, instead of looking at one giant poll request. It helps with rolling back, if you have a fire in production, and you need to roll back, while your commit messages will tell you where you need to be.

[00:02:05]
They also help with associating code with an external ticket tracker, or a GitHub issue. We, unfortunately use GEO at work, so I usually put the GEO ticket number in my commit message.
>> Nina Zakharenko: If you use GitHub, I'm gonna show you guys how to link to issues within your commensurator in the course, and they're actually be a nice clickable link in GitHub.

[00:02:38]
So an anatomy of a good commit message. Unfortunately, I see a lot of people commit with git commit-m all the time. And that's fine if your commits are brief, if your codes not doing a lot. But sometimes your commit encapsulates a really complicated idea, and in that case, the one line commit message is really not enough.

[00:02:59]
What you wanna do is add a descriptive body to your commit message after a new line.
>> Nina Zakharenko: Git is going to truncate that message, I think it's 69 characters by default. If you try to look at the commits on GitHub, it'll be dot, dot, dot, after 69 characters.

[00:03:19]
It's better to just keep them short, so that people aren't kept guessing.
>> Nina Zakharenko: And if you're commit message is already longer than 69 characters, it probably deserves a commit message description at this point. For that one line description, the commit message should be in the future tense, meaning fix, instead of fixed.

[00:03:47]
This short subject, the blank line. And lastly, a description. The description should be context. Don't explain how you did something. Don't say you moved file A to B. We can figure that out by looking at commit. The interesting information here, is how you did something. The code will describe what you did.

[00:04:08]
You should describe how you did it, describe the current behavior, give a short summary of why the fix is needed. Mention any side effects of your code. And this description should be broken into 72 character lines for best formatting.
>> Nina Zakharenko: Good commits are important. They have good commit messages.

[00:04:31]
They should generally encapsulate one logical idea. They shouldn't introduce any breaking changes, so when you commit, your test should pass.
>> Nina Zakharenko: It shouldn't leave your code in a broken state.