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 Threaded View
HBase >> mail # dev >> Describing your patches, writing release notes, a year later


Copy link to this message
-
Re: Describing your patches, writing release notes, a year later
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]>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]>
> Date: Mon, Mar 26, 2012 at 3:52 PM
> Subject: Describing your patches, writing release notes
> To: [EMAIL PROTECTED]
>
>
> 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
>
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