What makes a good commit message

There’s a useful conversation happening in an internal Automattic P2 I thought I’d take the liberty to share.

From Mike:

Consider the audience when you write a commit message. What is that audience? It’s at least two groups of people:

  • Your coworkers: You’re telling everyone else what you did. Commit messages are one to many, asynchronous and textual. Sounds like email, so write the commit message like an email. The first line should be a descriptive subject. The next line should be blank (as a separator). Then comes the body of the message. Write everything as if you’re describing it to Nikolay.
  • Your future self: Think back on the times you were fixing something and needed to understand why an old commit was made. How often was the commit message useful? How often was it your own useless commit message? The commit message should say what the problem was (repro steps?), how you fixed it (briefly – the code itself gives more details), and why you changed what you did. That way the shiny pants people of the future have the information they need to decide if they can safely change your code.

From Matt:

I think as a company we need better commit messages. Very often in our messages we say what is happening but not the why, and most importantly the context of the change. I’m going to pick on this changeset, but you could really pick almost anything:

[link to changeset]

4 lines changed, with the message:

“Fixing incorrect $blogid variable, should be $blog_id.
Check if $current_blog is === false before trying to reset it.”

First a good thing: it’s a multi-line message, which is nice. Commit messages can use as many lines as you like, and be as verbose as you like.

However if I were to come across this changeset 3 years from now, say if I were debugging a similar area in the code, I’d have no idea why this change happened. The message might as well be blank, since it doesn’t really say anything I couldn’t tell in 2 seconds from looking at the diff. Some useful context would be:

  • What bug did this code cause? (This is most important.) Why change it?
  • Is there a relevant discussion, either on a P2 or in Trac?
  • Who was involved in the fix, IE who else would have context for this change either because they reported the bug or reviewed the fix.

From Lance:

Good commit messages are my gospel. The actual syntax should vary by context, though. For theme commits, for example, we always start with the theme name up front.

But, the goal of giving context and pointing to related items is key.

I personally don’t think long commit messages are better. Instead, point to a Trac ticket or P2 post with all the gory details.

Aside

Writing beginner level tutorials. A number of useful tips. My favorite: “use words and phrases that your reader can Google to find more information.” For producers of documentation, I think the biggest challenge is putting yourself in the mindset of the reader. The second biggest challenge is closing the feedback loop between the person who has the knowledge and the person who wants the knowledge.

Om Malik on ten years of blogging

Today we differentiate between blogging on blogging platforms and sharing on social platforms, but that is just semantics. The essence of blogging is not defined by a platform but by what I learned from Dave and his blogging platform — that media now is raw, collaborative and instantaneous.

[…]

Blogging is communal: In 2008, I wrote that “blogging is not just an act of publishing but also a communal activity. It is more than leaving comments; it is about creating connections.” That is the single biggest lesson learned of these past 10 years. Every connection has lead to a new idea, new thought and a new opportunity.

Being authentic in your thoughts and voice is the only way to survive the test of time.

Being wrong is as important as being right. What’s more important — when wrong, admit that you are wrong and listen to those who are/were right.

Om Malik — My 10 years of blogging: Reflections, Lessons & Some Stats Too

Aside

In other words, my theory is: Cheating (on a systematic level) happens because students try to get an edge over their peers/competitors. Even top-notch students cheat, in order to ensure a perfect grade. Fighting cheating is not something that professors can do well in the long run, and it is counterproductive by itself. By channeling this competitive energy into creative activities, in which you cannot cheat, everyone is better off.

Panos Ipeirotis — Why I will never pursue cheating again. A computer scientist teaching in a business school details a year of trying to combat cheating on assignments. Overall, he spent 45 hours addressing the problem during a 32 hour lecture course, and 22 of 108 enrolled students admitted cheating. Solutions could include:

  • Public projects – All of the work ends up public, so embarrassment is the deterring factor.
  • Peer review – Students have to present their work in class, and are judged by others.
  • Competitions – Grades are performance-based (e.g. students build websites to attract the greatest number of unique visitors).

Takeaway: If plagiarism is your biggest worry, you’re doing it wrong.

Plugins for publishers, April 2011 edition

The following are WordPress plugins I find myself using and recommending regularly. In the interest of making this available to everyone, here’s the full list:

  • WordPress.com Custom CSS – Use your own CSS to tweak your website without modifying your theme’s files. Includes a revision history so you can always backtrack to prior versions. This is a feature WordPress.com charges $14.97/year for and has saved the J-School significant pain.
  • Co-Authors Plus – Assign multiple bylines to an article. You’ll need to edit your theme templates too for the multiple bylines to appear.
  • W3 Total Cache – Speed up the load time of your website with caching. Caching takes a generated page of your website and stores it statically for future use.
  • After the Deadline – Spelling, style, and grammar checker powered by artificial intelligence. Catches misused words, passive voice, and cliches.
  • Edit Flow – Move your editorial workflow into WordPress with custom post statuses, editorial comments, and calendar and story budget views.
  • Post Author Box – Add an informational box about the author to the beginning or ending of every post (or any other post type). Can also be used to add the byline if your theme doesn’t support bylines.
  • Google Calendar Events – Parses Google Calendar feeds and displays the events as a calendar grid or list on a page, post or widget. It’s the Google Calendar widget you always wanted.
  • Audio Player – Embed MP3 files in your content with a simple shortcode.
  • JSON API – For the programmatically-inclined, access all of your content through a JSON API. Useful for pulling content into your website with jQuery.
  • Twitter Tools – Automatically publish your articles to Twitter, and pull in your most recent tweets into a widget area.
  • Subscribe to Comments – Allow commenters to subscribe to email notifications on threads they’ve commented on. Increase repeat visitors and engagement.
  • Emphasis – Paragraph- and sentence-level linking and highlighting. Originally developed for nytimes.com, Michael Donohoe open-sourced the code and Ben Balter made it into a WordPress plugin. Every website should have emphasis.
  • Restrict Multisite Plugins – For those running multisite instances, allow your users to activate only a limited number of approved plugins. Interface is very similar to WordPress’ network theme management.

Also, as a part of the documentation we’re continually preparing for the J-School, here are the criteria I follow for adding new plugins:

  • GPL-compatible – We can only install plugins on our server that are compatible with the GNU General Public License. This ensures we have the legal right to modify the plugin if it breaks, and make it available to all members of our community. All WordPress.org plugins should be compatible. The license must be packaged with the plugin. Unfortunately, Creative Commons licenses are not GPL-compatible.
  • Regularly updated and well-rated – The plugin has been updated in the last 6 months or so by its author. WordPress adds new features regularly, so it’s necessary the developer keep the plugin compatible with the latest version. Active users can also indicate whether the most recent version of the plugin is compatible with the most recent version of WordPress. You can find this information on the right hand of the plugin’s profile page.
  • Performs well – A couple of ways you can see whether it’s a good plugin are googling the name of the plugin to see if there’s any negative feedback, or looking in the support forums. If there are a lot of site comments or discussion threads complaining about problems with the plugin, it’s usually a bad sign.