Commit messages

[Sergio Schvezov]

On Wed, Jan 20, 2016 at 12: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>
>
> {Closes,Updates} #<bug number>[,<bug number>]
>
"""
>

We use git-dch for generating changelogs, Closes is automatically picked
up, Updates would need to be passed in


>
> 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
>
> --
> snappy-devel mailing list
> snappy-devel at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/snappy-devel
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/snappy-devel/attachments/20160120/bae5ea4f/attachment-0001.html>