Thanks Enis. I'm on board with those two.
On Sat, May 11, 2013 at 9:33 AM, Enis Söztutar <[email protected]> wrote: > Thanks J-D for bringing this up. (You are my hero, etc etc) > > There are two related topics here: > > - Release notes / better documentation: This is a must and reviewers > should just enforce it to the patch author. Also I think the reviewer > should not accept a new feature, configuration option, or significant > change without a release note and user level documentation. Adding release > notes is good, but we cannot expect the users to refer to release notes to > learn about new configuration options. > For example, we should not have merged snapshots without committing the > documentation patch. > > - Patch documentation : independent of the discussions in the jira, the > patch itself is a beast of its own. Having an itemized list, which lists > what the patch does at the code level helps a lot with the reviews. > Otherwise, as a reviewer, you have to reverse engineer the changes done, > and in a bottom up way. it is much easier to do a review with a top-down > description. I am talking about something like this: > https://reviews.apache.org/r/9314/ > > Enis > > > > On Fri, May 10, 2013 at 5:17 PM, Andrew Purtell <[email protected]> > wrote: > > > Hi Ted, > > > > I will log a JIRA with an empty description if it is a subtask and the > > title makes it obvious. Then comments with status updates. Those JIRAs > are > > like a to do list. On the other hand for new features I will write up a > > detailed description plus a design document. Is there a difference > between > > those two situations or do you advocate something different for the > former? > > That's fine, but if so, then what exactly should I do differently? Maybe > > like: > > > > Title: "[Feature] Subtask" > > > > Description: "Implement $subtask" > > > > J-D? > > > > I try to exercise good judgement. If you can point out specific examples > > that should be done differently in your opinion and what should be done > > differently, that would be great. > > > > On Saturday, May 11, 2013, Ted Yu wrote: > > > > > I agree with J-D. > > > > > > New JIRAs are being logged daily, some with empty description. > > > > > > Cheers > > > > > > On Fri, May 10, 2013 at 4:37 PM, Jean-Daniel Cryans < > [email protected] > > <javascript:;> > > > >wrote: > > > > > > > Guys, > > > > > > > > Last year I wrote this note to the dev list and got feedback in the > > > > likes of: "Big +1", "+1", "Amen!", "JD you're my hero". > > > > > > > > I feel a refresher is in order. > > > > > > > > Thanks! > > > > > > > > J-D > > > > > > > > ---------- Forwarded message ---------- > > > > From: Jean-Daniel Cryans <[email protected] <javascript:;>> > > > > Date: Mon, Mar 26, 2012 at 3:52 PM > > > > Subject: Describing your patches, writing release notes > > > > To: [email protected] <javascript:;> > > > > > > > > > > > > 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 > > > > > > > > > > > > > -- > > Best regards, > > > > - Andy > > > > Problems worthy of attack prove their worth by hitting back. - Piet Hein > > (via Tom White) > > > -- Best regards, - Andy Problems worthy of attack prove their worth by hitting back. - Piet Hein (via Tom White)
