Describing your patches, writing release notes

[Jean-Daniel Cryans <jd...@apache.org>]

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

Re: Describing your patches, writing release notes

[Nicolas Spiegelberg <ns...@fb.com>]

In addition to release notes on configuration items, we should also
include the level of stability for the feature.  For example, although
we're feature complete on HBASE-4218, we're currently only using it for
in-memory compression so it can have some simmering time to find weird
bugs.  I think I would be hesitant about how much help I give on
HBASE-4218, because right now it would be good to limit usage to people
who can read the diff and understand it to debug.  'compaction.ratio' on
the other hand is a pretty safe config to change and I would actually
encourage the common user to play around with it.  Does
'hbase.online.schema.update.enable' even need to be documented?  It's only
false for right now while people are beta testing it.  Soon, it should be
set to true and people should not have to know that it exists.

Basically, right now, all config options are created equal in
documentation.  We need a way to distinguish between configs that we
actively want people to tweak, configs that are 'welcome to the bleeding
edge. Good luck', and configs that are 'we don't know how useful this is.
Just being proactive'.

Also note that, just because a feature is new to 0.94, that doesn't infer
maturity.  A small feature matures extremely quickly.  A large feature
that was committed right after the 0.92 cut and heavily used may be more
mature than a 0.92 feature that is lightly used.



On 3/26/12 4:59 PM, "Jonathan Hsieh" <jo...@cloudera.com> wrote:

>+1.
>
>Let's add these notes here?
>
>http://wiki.apache.org/hadoop/Hbase/HowToCommit
>
>Jon.
>
>On Mon, Mar 26, 2012 at 3:57 PM, Todd Lipcon <to...@cloudera.com> wrote:
>
>> Big +1. I think the commit messages that FB uses on their 0.89-fb
>> branch are a great example to follow. It's handy to have the data
>> right there in SVN, and if people are agreeable to it, I'd encourage
>> us to all start to follow a similar convention where possible. Look at
>> the Linux git history for good examples of how another project manages
>> this -- very informative commit messages for the most part.
>>
>> Also big +1 on release notes - any time configs are added/removed, the
>> release notes field should be mandatory. And highly recommended in the
>> other situations that JD mentioned.
>>
>> -Todd
>>
>> On Mon, Mar 26, 2012 at 3:52 PM, Jean-Daniel Cryans
>><jd...@apache.org>
>> wrote:
>> > 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=1323617
>>7&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#c
>>omment-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
>>
>>
>>
>> --
>> Todd Lipcon
>> Software Engineer, Cloudera
>>
>
>
>
>-- 
>// Jonathan Hsieh (shay)
>// Software Engineer, Cloudera
>// jon@cloudera.com

Re: Describing your patches, writing release notes

[Jonathan Hsieh <jo...@cloudera.com>]

+1.

Let's add these notes here?

http://wiki.apache.org/hadoop/Hbase/HowToCommit

Jon.

On Mon, Mar 26, 2012 at 3:57 PM, Todd Lipcon <to...@cloudera.com> wrote:

> Big +1. I think the commit messages that FB uses on their 0.89-fb
> branch are a great example to follow. It's handy to have the data
> right there in SVN, and if people are agreeable to it, I'd encourage
> us to all start to follow a similar convention where possible. Look at
> the Linux git history for good examples of how another project manages
> this -- very informative commit messages for the most part.
>
> Also big +1 on release notes - any time configs are added/removed, the
> release notes field should be mandatory. And highly recommended in the
> other situations that JD mentioned.
>
> -Todd
>
> On Mon, Mar 26, 2012 at 3:52 PM, Jean-Daniel Cryans <jd...@apache.org>
> wrote:
> > 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
>
>
>
> --
> Todd Lipcon
> Software Engineer, Cloudera
>



-- 
// Jonathan Hsieh (shay)
// Software Engineer, Cloudera
// jon@cloudera.com

Re: Describing your patches, writing release notes

[Todd Lipcon <to...@cloudera.com>]

Big +1. I think the commit messages that FB uses on their 0.89-fb
branch are a great example to follow. It's handy to have the data
right there in SVN, and if people are agreeable to it, I'd encourage
us to all start to follow a similar convention where possible. Look at
the Linux git history for good examples of how another project manages
this -- very informative commit messages for the most part.

Also big +1 on release notes - any time configs are added/removed, the
release notes field should be mandatory. And highly recommended in the
other situations that JD mentioned.

-Todd

On Mon, Mar 26, 2012 at 3:52 PM, Jean-Daniel Cryans <jd...@apache.org> wrote:
> 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



-- 
Todd Lipcon
Software Engineer, Cloudera

Re: Describing your patches, writing release notes

[Otis Gospodnetic <ot...@yahoo.com>]

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 <jd...@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
>