-Re: Describing your patches, writing release notes, a year later
On Fri, May 10, 2013 at 5:17 PM, Andrew Purtell <[EMAIL PROTECTED]> 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
> Title: "[Feature] Subtask"
> Description: "Implement $subtask"
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.
>> > 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 ----------
>> > Date: Mon, Mar 26, 2012 at 3:52 PM
>> > 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