Commit messages

[Gustavo Niemeyer]

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>

{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.

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/snappy-devel/attachments/20160120/1ce3a07a/attachment-0001.html>