Describing your patches, writing release notes, a year later

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

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 <jd...@apache.org>
Date: Mon, Mar 26, 2012 at 3:52 PM
Subject: Describing your patches, writing release notes
To: dev@hbase.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, a year later

[Andrew Purtell <ap...@apache.org>]

Thanks Enis. I'm on board with those two.


On Sat, May 11, 2013 at 9:33 AM, Enis Söztutar <en...@gmail.com> 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 <ap...@apache.org>
> 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 <
> jdcryans@apache.org
> > <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 <jdcryans@apache.org <javascript:;>>
> > > > Date: Mon, Mar 26, 2012 at 3:52 PM
> > > > Subject: Describing your patches, writing release notes
> > > > To: dev@hbase.apache.org <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
> > > > (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
> > > >
> > >
> >
> >
> > --
> > Best regards,
> >
> >    - Andy
> >
> > Problems worthy of attack prove their worth by hitting back. - Piet Hein
> > (via Tom White)
> >
>



-- 
Best regards,

   - Andy

Problems worthy of attack prove their worth by hitting back. - Piet Hein
(via Tom White)

Re: Describing your patches, writing release notes, a year later

[Enis Söztutar <en...@gmail.com>]

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 <ap...@apache.org> 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 <jdcryans@apache.org
> <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 <jdcryans@apache.org <javascript:;>>
> > > Date: Mon, Mar 26, 2012 at 3:52 PM
> > > Subject: Describing your patches, writing release notes
> > > To: dev@hbase.apache.org <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
> > > (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
> > >
> >
>
>
> --
> Best regards,
>
>    - Andy
>
> Problems worthy of attack prove their worth by hitting back. - Piet Hein
> (via Tom White)
>

Re: Describing your patches, writing release notes, a year later

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

On Fri, May 10, 2013 at 5:17 PM, Andrew Purtell <ap...@apache.org> 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?

Yeah, subtasks... They are created by default without a description so
I guess as long as it's really a subtask and not a whole new feature
you're adding then IMO it's fine just leaving the title populated.

I'm also in favor of good judgment and doing what makes sense. Putting
the same text in the title and the description, for example, would be
silly assuming it's something trivial. A subtask  without a
description for a sizable piece of code could be without a description
if it refers to something clearly explained in the parent jira's
design document. Then again, we're back to good judgment.

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

Was this for me or Ted? Regardless, here's an example (sorry Jimmy
*smile*) where a patch was posted without any comments which I then
asked for: https://issues.apache.org/jira/browse/HBASE-8437?focusedCommentId=13652151&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-13652151

>
> 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 <jdcryans@apache.org<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 <jdcryans@apache.org <javascript:;>>
>> > Date: Mon, Mar 26, 2012 at 3:52 PM
>> > Subject: Describing your patches, writing release notes
>> > To: dev@hbase.apache.org <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
>> > (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
>> >
>>
>
>
> --
> Best regards,
>
>    - Andy
>
> Problems worthy of attack prove their worth by hitting back. - Piet Hein
> (via Tom White)

Re: Describing your patches, writing release notes, a year later

[Andrew Purtell <ap...@apache.org>]

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 <jdcryans@apache.org<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 <jdcryans@apache.org <javascript:;>>
> > Date: Mon, Mar 26, 2012 at 3:52 PM
> > Subject: Describing your patches, writing release notes
> > To: dev@hbase.apache.org <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
> > (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
> >
>


-- 
Best regards,

   - Andy

Problems worthy of attack prove their worth by hitting back. - Piet Hein
(via Tom White)

Re: Describing your patches, writing release notes, a year later

[Ted Yu <yu...@gmail.com>]

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 <jd...@apache.org>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 <jd...@apache.org>
> Date: Mon, Mar 26, 2012 at 3:52 PM
> Subject: Describing your patches, writing release notes
> To: dev@hbase.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
>