Suggestion to improve the documentation of changes in WHATSNEW.txt

[Christian Perrier]

Hello dear Samba developers and contributors,

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.

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.

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).

Do you folks think that something should be improved in that matter?


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.