Home | About | Sematext search-lucene.com search-hadoop.com
NEW: Monitor These Apps!
elasticsearch, apache solr, apache hbase, hadoop, redis, casssandra, amazon cloudwatch, mysql, memcached, apache kafka, apache zookeeper, apache storm, ubuntu, centOS, red hat, debian, puppet labs, java, senseiDB
 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
NEW: Monitor These Apps!
elasticsearch, apache solr, apache hbase, hadoop, redis, casssandra, amazon cloudwatch, mysql, memcached, apache kafka, apache zookeeper, apache storm, ubuntu, centOS, red hat, debian, puppet labs, java, senseiDB