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

Switch to Threaded View
HBase >> mail # dev >> Describing your patches, writing release notes


Copy link to this message
-
Re: Describing your patches, writing release notes
Amen!
Here is something on a very related topic:
http://www.jroller.com/otis/entry/commit_messages_as_communication_mechanism 
Otis
----
Performance Monitoring SaaS for HBase- http://sematext.com/spm/hbase-performance-monitoring/index.html

----- Original Message -----
> From: Jean-Daniel Cryans <[EMAIL PROTECTED]>
> To: [EMAIL PROTECTED]
> Cc:
> Sent: Tuesday, March 27, 2012 6:52 AM
> Subject: Describing your patches, writing release notes
>
> 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
>