Commit messages

Dustin Kirkland kirkland at canonical.com
Wed Jan 20 21:02:12 UTC 2016


On Wed, Jan 20, 2016 at 9:53 PM, Gustavo Niemeyer
<gustavo.niemeyer at canonical.com> wrote:
> Hello there,
>
> We had a meeting today prompted by the QA team about the fact they're having
> a hard time keeping track of all the activity going on, which I can imagine
> must be quite the challenge right now.
>
> As we discussed, one way we can help them significantly is by improving and
> standardizing our commit messages, which is easy on us and a big help for
> them and even for ourselves. So the proposal below is an attempt at that,
> and is based on a mix of best practices evolved in other projects.
>
> This convention should be used in two places: the Pull Request description
> in GitHub, and in the commit that merges the change into the master branch.
> Luckily, GitHub defaults the latter to the former assuming the GUI is used
> for the merge, so it should be quite straightforward. Conveniently, it also
> means that reviewers can collaborate on getting the change description just
> right, and that the responsibility for enforcing this convention is entirely
> onto the shoulders of people merging changes, which makes sense.
>
> So, for the actual proposal. My initial recommendation would be the
> following format:
>
> """
> <affected packages>: <summary in lowercased imperative mood ("add", not
> "added"), no full stop>
>
> <description with prose in proper English>

I suggest one additional "best practice" here, in the description...

Please explain the "why", more so than the "what".  The "what" changed
is easy to see in the diff.  It's the "why" that someone, somewhere
hours/days/weeks/months/years from now will wonder.  Why did you make
that change?  Why did you implement it that way?  All of the rest of
the questions are implicitly answered elsewhere (when? what? how?).
It's the "why" that's really interesting!

> {Closes,Updates} #<bug number>[,<bug number>]
> """
>
> A more concrete example:
>
> """
> asserts,daemon,cmd/snap: introduce "asserts" subcommand
>
> New "asserts" subcommand allows querying the database of known assertions.

It's truly fantastic that this new subcommand queries the database...I
could see that in the source code...but "why" was that feature
implemented, why is that useful or valuable?  ;-)

Cheers,
:-Dustin

> Updates #123456,782345
> Closes #415211
> """
>
> Some details:
>
> <affected packages>: Comma separated list of Go package paths that were
> affected, starting after ".../ubuntu-core/snappy/". Although redundant with
> the commit content, the summary here gives a great deal of useful context
> for interpreting the follow up sentence, so I suggest keeping it. If there
> are too many affected packages for a reasonable summary length, just replace
> the list by the word "many". It's also okay to have just a prefix when there
> are many affected packages under a common path (no wildcards please..
> "cmd:", not "cmd/*").
>
> <summary>: Quick overview of the change. Lowercased, no full stop at the end
> (no dots), and in imperative mood, to bring consistency for a pleasant
> sequential read and to encourage necessary terseness ("fix foo", "remove
> bar", "support baz", etc).
>
> <description>: A proper English text in free form, oriented for a human to
> read when looking for more comprehension of the change. Let's please use
> proper capitalization and punctuation here.
>
> <bug number>: Optional bug number. Use Closes if the pull request fixes the
> issue altogether, and/or Updates if it's related to the issue but does not
> resolve the issue. Multiple issues are separated by a comma, single #, if it
> both Updates and Closes, these go in separate lines. Being precise with the
> format here makes it easier to parse if we need to.
>
>
> Does that sound reasonable? If so, let's please keep an eye open when
> reviewing and merging changes so we put it in place right away.
>
>
> gustavo @ http://niemeyer.net
>
> --
> snappy-devel mailing list
> snappy-devel at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/snappy-devel
>



More information about the snappy-devel mailing list