#128 Write standards for commit messages
Closed: Invalid None Opened 9 years ago by roshi.

We need to have a standard for commit messages going forward - both for our sanity as well as generating nice release notes from git commit logs.

Background

One of the examples we've found that we like is the way [[ https://github.com/angular/angular.js/blob/master/CHANGELOG.md | Angular ]] does their release notes. We can emulate this pretty easily - but we need to have a standard for commit messages.

Angular does fix(foo): description for each commit which is fairly easy to read and easyish to parse.

I propose we have commit messages like this:

commit type :: component :: description of what was committed.

Additional lines with more explanation if needed.

Some examples of 'commit types:'

  • fix
  • feature
  • doc
  • refactor

I'm sure I didn't get everything, but I think it would be a good base to work off of.

Thoughts?


commit type :: component :: description of what was committed.

One thing that comes to mind is that it would be challenging not to exceed 50 characters (see below) in the first line of a commit message with the format mentioned above. Not sure if that would be a big deal, just a thought.

As a general rule, your messages should start with a single line that’s no more than about 50 characters and that describes the changeset concisely, ...
-- http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project

I usually use

component: description

as the title, for example:

python_utils: replace listlike() with iterable() and sequence()

It makes the commit messages more readable, because you immediately know where the changed happened. I wouldn't object if everybody used it, although I'm not sure we should mandate it, because sometimes your change simply doesn't fit clearly any component. For example:

improve PEP8 compliance

throughout the source code. You can hardly put a component in there.

I wouldn't mind if we added also the type of the commit (fix, feature, etc), although we must be very careful about the title length. Long titles are uncomfortable to work with with the standard git tools (git branch, gitg, etc). vim will tell you once you've crossed the recommended title length by showing you a red background, and I recommend everyone to adhere to that. There are some sinners in our team, by looking into our git log.

All of this commit markup would be nice to have for our (human) consumption. But I'm not really sure if it's useful for automated processing. We would need to follow it very strictly and make some compromises (state some component even if it makes no sense, for example). Also, I'm bit skeptical about the very concept of generated release notes. If the release notes are to be use useful, they need to be crafted by hand. Release notes (or at least what I understand under that term) should be a higher-level overview of the changes. Git commit messages are the opposite, the lowest level it can get. For Taskotron releases, I would like to produce both. I would like to have a human readable description of the most important changes (that includes some helpful information how to convert old stuff to new stuff, for example, links to example files showcasing the changes, etc) and a (link to) git commit log (which is very technical, includes a lot of unimportant information from the user perspective - who cares that we reformatted the code according to PEP8, no one - and is mainly targeted at developers following our code and sending occasional patches, or check developers).

! In #203#7, @kparal wrote:
I usually use
component: description
as the title, for example:
python_utils: replace listlike() with iterable() and sequence()
It makes the commit messages more readable, because you immediately know where the changed happened. I wouldn't object if everybody used it, although I'm not sure we should mandate it, because sometimes your change simply doesn't fit clearly any component. For example:
improve PEP8 compliance

That would fit in under "refactor" I think.

refactor: improve PEP8 compliance

So some commit types wouldn't have a component associated with them.

throughout the source code. You can hardly put a component in there.

I wouldn't mind if we added also the type of the commit (fix, feature, etc), although we must be very careful about the title length. Long titles are uncomfortable to work with with the standard git tools (git branch, gitg, etc). vim will tell you once you've crossed the recommended title length by showing you a red background, and I recommend everyone to adhere to that. There are some sinners in our team, by looking into our git log.

All of this commit markup would be nice to have for our (human) consumption. But I'm not really sure if it's useful for automated processing. We would need to follow it very strictly and make some compromises (state some component even if it makes no sense, for example). Also, I'm bit skeptical about the very concept of generated release notes. If the release notes are to be use useful, they need to be crafted by hand. Release notes (or at least what I understand under that term) should be a higher-level overview of the changes. Git commit messages are the opposite, the lowest level it can get. For Taskotron releases, I would like to produce both.

I think there might need to be some hand editing of the generated RST for adding any of the high-level stuff that should be there for the release notes. I don't know that we need both as separate entities. Auto-generating a outline from git logs would be useful before manually editing things.

I would like to have a human readable description of the most important changes (that includes some helpful information how to convert old stuff to new stuff, for example, links to example files showcasing the changes, etc) and a (link to) git commit log (which is very technical, includes a lot of unimportant information from the user perspective - who cares that we reformatted the code according to PEP8, no one - and is mainly targeted at developers following our code and sending occasional patches, or check developers).

For some projects, like a word processor, email client, chat client, etc., that makes sense. But our user base is going to be more technical just because of the nature of the problem we're attempting to solve - so I don't think git log summaries in the release notes will confuse anyone. Especially if our git logs are clean all the way through.

I just came across this systemd commit:
http://cgit.freedesktop.org/systemd/systemd/commit/?id=abee28c56d

Please note that something like "bugfix" can be easily included in the commit body instead of the commit title. That approach would not inflate the title while still keeping the ability to mark the commit with a specific tag (we just need to set up some standards). It would also allow us to put several tags into the commit.

Just an idea.

Login to comment on this ticket.

Metadata