<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Wed, Jan 20, 2016 at 12:53 PM, Gustavo Niemeyer <span dir="ltr"><<a href="mailto:gustavo.niemeyer@canonical.com" target="_blank">gustavo.niemeyer@canonical.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">Hello there,<div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div><div>So, for the actual proposal. My initial recommendation would be the following format:</div><div><br></div><div>"""</div><div><affected packages>: <summary in lowercased imperative mood ("add", not "added"), no full stop></div><div><br></div><div><description with prose in proper English></div><div><br></div><div>{Closes,Updates} #<bug number>[,<bug number>] <br></div></div></blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div>""" <br></div></div></blockquote><div><br></div><div>We use git-dch for generating changelogs, Closes is automatically picked up, Updates would need to be passed in<br> <br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><br></div><div>A more concrete example:</div><div><br></div><div>"""</div><div>asserts,daemon,cmd/snap: introduce "asserts" subcommand</div><div><br></div><div>New "asserts" subcommand allows querying the database of known assertions.</div><div><br></div><div>Updates #123456,782345</div><div>Closes #415211</div><div>"""</div><div><br></div><div>Some details:</div><div><br></div><div><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/*").</div><div><br></div><div><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).</div><div><br></div><div><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.</div><div><br></div><div><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.</div><div><br></div><div><br></div><div>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.</div><div><br></div><div><div><br></div><div>gustavo @ <a href="http://niemeyer.net" target="_blank">http://niemeyer.net</a></div>
</div></div>
<br>--<br>
snappy-devel mailing list<br>
<a href="mailto:snappy-devel@lists.ubuntu.com">snappy-devel@lists.ubuntu.com</a><br>
Modify settings or unsubscribe at: <a href="https://lists.ubuntu.com/mailman/listinfo/snappy-devel" rel="noreferrer" target="_blank">https://lists.ubuntu.com/mailman/listinfo/snappy-devel</a><br>
<br></blockquote></div><br></div></div>