On Sunday, 12 September 2010 at 14:12, Stephen Swaney wrote: > Two commit messages - compare and contrast:
> Log Message: > ----------- > Fix bug #2147, fix bug #2158, remove VTOL Flak Cannon (doesn't make sense > lore-wise, and did too much friendly fire to be useful). That doesn't tell much about what the actual change was (and even if it doesn't need to be mentioned, that can't be determined from the message (unless you classify all changes with no useful message as irrelevant)). > Log Message: > ----------- > Fix lobby glitch to update everything when netPlayersUpdated is true > and force localOptionsReceived to be true as well, > since that is what controls the drawing routines. > > Fixes ticket:2136 This one tells what was changed, but not why, the reason is also hidden in the ticket. > Now imagine you are trying to make a Changelog. Which one is more useful > to you? > > Hint to forestall nitpicking over these specific msgs: > > One msg requires looking up the specific bug in Trac in order to > add something meaningful to the Changelaog. Both bad, the second slightly less because it's only one ticket to look up. :P > The other one provides something that can be cut & pasted. ... if you don't care about it actually telling the users what this change is about. My preferred commit message format is: "What was changed. Reason why it was done, maybe why it was done the way it was done, the tickets it fixes." So a short summary that's less than 80 characters, and a description with more details, if needed. git uses that format, and when you email a patch, the first line becomes the subject, and the rest the message body. So ideally commit message and patch are a self-contained unit, that should work well for changelog writing. _______________________________________________ Warzone-dev mailing list [email protected] https://mail.gna.org/listinfo/warzone-dev
