In this movie I want us to talk about writing commit messages and the best
practices for doing that.
Now in the last movie we did our first commit, and we gave it a really simple
single-line commit message that was just initial commit, pretty bland and boring
and even worse, it doesn't really describe what we were doing.
What you really want to do is have a commit message that describes the changes
that you're making in that commit set, so added file to project, that would be
more descriptive saying that we added this first file. That you added the
JavaScript to something, that you were fixing a bug.
We are labeling what we were doing in this change set so when we come back and
look at it later, we can just look at the commit message and know what's inside,
what's contained in that set.
So we want to have good descriptive commit messages.
There are also some other best practices that we should follow.
We want to start with a short single-line summary, less than 50 characters, keep it short.
Optionally, we can follow that by a blank line and then a more complete description.
Now if you are just making a tiny little change, a single-line summary will do
it, but if you're committing a change that has lots of changes, that take place
in lots of files, it might be worthwhile to have a more complete description.
Now the way we were doing it before from the single command line, that's a
little tricky to do inside those double quotes, but we can also use a text
editor to make these commit messages well, and that makes it easier to do
multiline commit messages.
Even then you want to keep those additional lines to less than 72 characters,
and that's because different people may be looking at your commit log from
different types of tools, they may be using Mac or Windows, viewing it on the
web, graphical user interfaces, they may be receiving this commit information
via email, so we want to limit it to 72 characters.
And you want to write commit messages in the present tense, not in the past
tense, you are labeling what this commit does, not what you--as the creator--were doing.
Label what it does. This fixes a bug, not I fixed a bug.
It's not about you, it's about what this commit is.
If you need to have bullet points that describe what happens you usually use
asterisk or hyphens, and you can add ticket tracking numbers from bugs
or support requests or develop a shorthand for your organization.
So maybe you put, for example, in square brackets at the beginning of your
message that you are messing with the CSS or the JavaScript or maybe you label
all bug fixes with bugfix:,
or put a tracking number in the front letting it know what sort of support
request ticket it goes with.
These kinds of decisions are really the personal preferences that you or your
organization will need to decide on.
But it's a good idea to pick standards like this and then stick with them and
get everyone to agree to it so that everyone working on the repository is using
the same set of conventions for their commit messages.
So you want to be clear and descriptive, so, for example,
Bad: "Fix typo", would be an example of a bad commit that doesn't really tell what's going on.
A good example would be "Add missing > in project section of HTML" much more
descriptive of what we were doing, what was going on, what is the typo, what
were we in here trying to fix.
Bad: "Update login code" that's pretty general, a good example "Change user
authentication to use Blowfish", right, much more descriptive about what was
going on and what we were doing with this change. Again, providing good labels on
the outside of the envelope and then another bad example would be to include
other comments in there that really aren't about the commit, so "Updates member
report, we should discuss if this is right next week".
Well, this commit is going to live in our repository potentially for years
and years and years having a comment that that says we should discuss if this
is right next week.
This isn't email, right, this in not a way to communicate with our team members,
we can do that using other tools.
What we want to do here is just provide a good label for what's inside the commit.
So let's take a look at an example of one good commit.
So here's an example of a good commit message, it's got a tracking number, this
is the convention that this company is going to use for tracking support tickets,
t23094 - Fixes bug in admin logout.
That's a little bit vague, but we've got something underneath it that gives it
more description, When an admin logged out of the admin area, they could not
log in to the members area because their session :user_id was still set to the admin ID.
This patch fixes the bug by setting session :user_id to nil when any user
logs out of any area.
Notice that it describes what the problem was and then describes what the
solution was as well. So it's all there.
If we come, and we just look at this, we don't have to actually look at the
code, and we have a good idea of what the creator of this commit was trying to do.
It's a good label on the commit to let us know what it's going to do when we add
this change set to the project.
Now I mentioned that you should keep the first line to less than 50 characters
and then subsequent lines to less than 72 characters.
Just as a reference, the longest line in this commit is about 60 characters wide.
So that gives you an idea of how much you can fit on a line, you can go a little
further than this, this is about 60 characters wide, and then you just need to
hit a Return, and then you can keep typing.
So hopefully right here from the start, I can get you thinking about what a good
descriptive commit message is so that all of our commits will be well labeled.
That's going to be really important with Git, because remember Git works with
these commit snapshots and allows us to exchange them between repositories.
So it's very important that we have well labeled commits so that if Bob makes a
commit and then Mary is thinking about incorporating that commit into her
project, she can look at it, see what that commit is, and decide to merge it into
her project so that it becomes part for her project as well.
So having well-labeled commits is really important.
In the next movie we'll take a look at how we can look at the log of previous commit messages.