Big +1. I think the commit messages that FB uses on their 0.89-fb branch are a great example to follow. It's handy to have the data right there in SVN, and if people are agreeable to it, I'd encourage us to all start to follow a similar convention where possible. Look at the Linux git history for good examples of how another project manages this -- very informative commit messages for the most part.
Also big +1 on release notes - any time configs are added/removed, the release notes field should be mandatory. And highly recommended in the other situations that JD mentioned. -Todd On Mon, Mar 26, 2012 at 3:52 PM, Jean-Daniel Cryans <[email protected]> wrote: > Hi devs, > > Our community has really been growing recently and it's getting harder > and harder to keep up with what's going on in the project. I can think > of two things that would really help (me at least). > > 1) Explaining your patches > > Whether you need to go back to a jira that's been fixed months ago or > you're just trying to grok the progression of another, not having any > description of what's being done in a particular patch attached to a > jira has at least two bad effects: a developer has to either spend > time trying to understand the changes or he simply moves on and misses > the party bus. It's much more efficient if the author describes what > he did. > > Bad examples of comments coming along patches: > > "Here's a patch" > "v2" > "First pass" / "Second pass" / "Final" > > Unless the required work was already pretty explicit like adding > documentation or fixing something small, this is not helping anyone > (including the author). > > Ok examples: > > "To fix the bug I added X in Y" > "In this patch I refactored Foo" > > This might be enough but if the patch is >50kb then you better come up > with something better than that. > > Good examples would include: > > - A description of how your patch is trying to solve the issue. > - Explanations for certain parts you think are sketchy or tricky. "I > tried to do X but because of Y it was impossible, had to hack this > instead". "This might look like a big shotgun surgery, but 90% of this > patch is just a big refactor because I extracted these methods into a > separate class". > - An overview of the unit tests you added or had to change and why. > > If you're zealous, or working on a very big patch, you might want to > list the changes per file along with a concise description. Example: > > https://issues.apache.org/jira/browse/HBASE-5616?focusedCommentId=13236177&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13236177 > > > 2) Writing release notes > > Sometimes one or two sentences can prevent having to read a whole jira. When: > > - You add a new feature, you should describe what needs to be > configured in order to enable it . > - You add a new configuration, you should list it there and give a few > tips on using it. > - You change a behavior, you should explicitly say how it used to work > and how it's going to work. > - You remove a feature/confg/behavior, you should list it there too. > (there's probably more I didn't think of) > > I would like to point out HBASE-4218 as an example of a jira that begs > for release notes (I was testing 0.94 and wondered how to enable it > last week), it's almost 500KB and it has almost no documentation which > is kinda sad since it looks like something you'd really want to use. > > Note that I'm not trying to say we shouldn't add documentation to the > reference guide (please do, as much as you can), but release notes are > easy to write and should be part of the process of resolving a jira. > > > Is there anything I'm missing? Does this sound reasonable? > > Thanks for reading, > > J-D -- Todd Lipcon Software Engineer, Cloudera
