Re: [ANNOUNCE] GIT 1.5.3

[Steven Grimm <koreth@midwinter.com>]

Junio C Hamano wrote:
> It's a tricky balancing act.  Not everybody is the end user who
> is only interested in using Porcelain.  The release note for a
> new release somehow needs to mention changes that would affect
> only plumbing users as well.
>   

No argument there, of course; it needs to be documented. But maybe not 
as the very first item at the top of the release notes, which people 
might expect to be organized in a "most user-visible first" order. I 
usually expect to see general descriptions of new features and critical 
bugfixes at the top of a program's release notes, with the option to 
keep reading if I want the low-level details.

Barring that, or even in addition to that, would it make sense to have 
separate "porcelain" and "plumbing" sections of the release notes? 
Obviously some changes straddle the two, but there are a lot that are 
pretty clear-cut one way or the other. Then end users can ignore the 
plumbing section and porcelain writers can jump straight to it.

-Steve