Suggestion to improve the documentation of changes in WHATSNEW.txt

[Karolin Seeger]

Hi Christian,

On Sun, Mar 01, 2009 at 02:22:28PM +0100, Christian Perrier wrote:
> As a "porter" of Samba (building packages for Debian and derivatives),
> I'm often puzzled by the identificaton of changes in the WHATSNEW.txt
> file.
> 
> In Debian BTS, we have several bugs reported against the samba package
> (http://bugs.debian.org/cgi-bin/pkgreport.cgi?src=samba). Several of
> them have been reported "upstream", thus in Bugzilla.
> 
> When a new samba version is released, we of course prepare new
> packages and one of the challenges we're facing is closing the
> relevant bug reports with proper version tagging (ie saying "this bug
> was fixed in package version X.Y.Z-n").
> 
> Here and there, it's sometimes difficult to find whether a given bug
> is really fixed in a new release and properly close it in our BTS. 
> 
> As an example, I can cite Bugzilla #5346 or #5996. Both are fixed in
> Samba 3.3.1. Both were originally reported in Debian
> (http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=454799 and
> http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=498704,
> respectively).
> 
> So, indeed, my upcoming upload of the first 3.3.1 package should close
> these Debian bugs.
> 
> However, WHATSNEW.txt does not mention them. One (#5346) is maybe
> considered a "minor" fix...but the other one is a new feature that
> would deserve being documented in WHATSNEW.txt. For sure, as bug
> submitter, I was notified when the fix was released....and I tagged
> "our" bug as "fixed-upstream" making it fairly easy to spot.
> 
> Still, some holes remain:
> - the bug fix is not documented in WHATSNEW.txt
> - the bug is not closed in Bugzilla
> 
> >From what I understand, WHATSNEW.txt is filled in by the release
> manager (ie Karolin) when she prepares the new version. However, it
> seems that it's fairly easy to miss something and end up with an
> improvement not being documented.
 
Yes, exactly. I am very glad that you mentioned this problem!
It's impossible to go through all the patches and see if they fix a bug
report or not. So I am really reliant on the developers. Please, please,
please mention the bug number in the commit messages!

> Couldn't there be some "policy" among committers to explicitely
> mention the Bugzilla bug that's fixed when a patch is committed in git
> so that it's easier to automagically build WHATSNEW.txt *and* mention
> what bugs are fixed.

This "policy" does exist, but is ignored sometimes. I am going to write a
Wiki page about contributing. The style of the commit messages will be
mentioned there. Maybe that helps. From time to time, there are mails
about this topic on the list, but new developers don't have a chance to
read them.
 
> Moreover, it would also help closing bugs: I sometimes "discovered"
> some Bugzilla bugs that are fixed for some time....but were not
> closed, probably because the committer forgot to close it (#5996 being
> one of these).

That's true! But I have no idea how to improve that. Going through the bug
reports from time to time helps, but it would be much easier if the
reporter and/or the developers would take care themselves.
 
> Do you folks think that something should be improved in that matter?

Yes, of course! :-) 

> PS: I feel the need to mention here that I'm not complaining at all. I
> admire the wonderful work done by all the team and I particularly have
> a great respect for the work done by Karolin in release management
> (just looking back one year and see how releases have been well
> published on schedule). So, really, this is an improvement
> suggestion...on somethign I don't have much control about.

Thanks! :-)

Christian, your comments and your work on the packages are very much
appreciated! And it really does not sound like complaining (at least in my
ears ;-). Thank you very much!

Karolin

-- 
SerNet GmbH, Bahnhofsallee 1b, 37081 Göttingen
phone: +49-551-370000-0, fax: +49-551-370000-9
AG Göttingen, HRB 2816, GF: Dr. Johannes Loxen
http://www.SerNet.DE, mailto: Info @ SerNet.DE