hbase-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Otis Gospodnetic <otis_gospodne...@yahoo.com>
Subject Re: Describing your patches, writing release notes
Date Tue, 27 Mar 2012 02:35:25 GMT
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 <jdcryans@apache.org>
> To: dev@hbase.apache.org
> 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
> 

Mime
View raw message