+1. Let's add these notes here?
http://wiki.apache.org/hadoop/Hbase/HowToCommit Jon. On Mon, Mar 26, 2012 at 3:57 PM, Todd Lipcon <[email protected]> wrote: > 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 > -- // Jonathan Hsieh (shay) // Software Engineer, Cloudera // [email protected]
