hbase-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Purtell <apurt...@apache.org>
Subject Re: Describing your patches, writing release notes, a year later
Date Sat, 11 May 2013 01:45:54 GMT
Thanks Enis. I'm on board with those two.


On Sat, May 11, 2013 at 9:33 AM, Enis Söztutar <enis.soz@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 <apurtell@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)

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message