Home | About | Sematext search-lucene.com search-hadoop.com
 Search Hadoop and all its subprojects:

Switch to Plain View
HBase >> mail # dev >> Describing your patches, writing release notes, a year later


+
Jean-Daniel Cryans 2013-05-10, 23:37
+
Ted Yu 2013-05-10, 23:43
+
Andrew Purtell 2013-05-11, 00:17
+
Enis Söztutar 2013-05-11, 01:33
Copy link to this message
-
Re: Describing your patches, writing release notes, a year later
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

Best regards,

   - Andy

Problems worthy of attack prove their worth by hitting back. - Piet Hein
(via Tom White)
+
Jean-Daniel Cryans 2013-05-11, 19:35