Ignore the previus email, not sure what combo of keys I pressed that it got sent :-P
On Wed, Jan 20, 2016 at 12:53 PM, Gustavo Niemeyer < [email protected]> 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>] > """ > > 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 > """ > To help out git-dch, just recall to add 'Updates' in there. *--meta-closes=**bug-close-tags* What meta tags to look for to generate bug-closing changelog entries. The default is ’Closes|LP’ to support Debian and Launchpad > > 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. > This sounds reasonable, I would like that this ends up in a CONTRIBUTING.md in master as github brings that to your attention when creating PRs.
-- snappy-devel mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/snappy-devel
