-Re: Describing your patches, writing release notes
Todd Lipcon 2012-03-26, 22:57
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.
On Mon, Mar 26, 2012 at 3:52 PM, Jean-Daniel Cryans <[EMAIL PROTECTED]> 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"
> "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:
> 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,
Software Engineer, Cloudera