[1796] in Kerberos_V5_Development
Re: Conventions for gnats PR tracking
daemon@ATHENA.MIT.EDU (Ken Raeburn)
Thu Sep 26 16:28:26 1996
To: "Barry Jaspan" <bjaspan@MIT.EDU>
Cc: krbdev@MIT.EDU
From: Ken Raeburn <raeburn@cygnus.com>
Date: 26 Sep 1996 16:27:45 -0400
In-Reply-To: "Barry Jaspan"'s message of Thu, 26 Sep 1996 12:45:25 -0400
> Fri Sep 20 16:52:07 1996 Barry Jaspan <bjaspan@mit.edu>
>
> * [krb5-admin/1234] configure.in: add unit-test directory
Any given PR number is only used in one category at any given time.
And it is possible to change the category of a PR. I'd suggest
leaving the category out.
Also, I think the primary reason for a change log file is as a log of
changes to source files, not as a log of PR numbers of bugs fixed.
I'd rather see the PR info at the end or otherwise not in the way of
skimming the standard changelog entries in their usual format.
At Cygnus, we've used styles like:
Fix PR 1234:
* configure.in: Test for function frobnicate.
* frobnicate.c (frob_thingy): New function.
* main.c: Call frob_thingy if thingy needs frobbing before
writing to disk.
and:
* configure.in: Look for frobnitz in library frob. Fixes PR
1235.
So the file names and function names are where you expect them to be
(if you're accustomed to reading standard emacs-generated changelog
files), and you can find the PR numbers if you're actually reading the
descriptions. (If you're not reading them, and you're not doing a
editor search through the file, you probably don't care. The one
other case I can see is trying to list all PRs fixed between two
dates, which can probably be done on the GNATS side.)
> o When you change a PR to state "closed," and the reason is that you
> fixed the bug or otherwise made the appropriate changes, list all of
> the files affected in the PR. If you listed all the files in the
> appropriate ChangeLog file(s), then you can just list the ChangeLogs.
> For example:
I haven't looked at how you're trying to use PRMS/GNATS, but we
usually put in there all the messages we exchange with customers
regarding the PR. This generally includes patches. If you're doing
things differently (only krbdev people submitting PRs, or not sending
out patches), then logging the list of files is a good idea. I'm not
100% convinced the version number is needed if the log entry is made
around the same time as the checkin, but it wouldn't hurt, and it'd
definitely be useful if the PR change was logged significantly after
the checkin. It does add more manual work to the PR handling process
though. We've long wanted some way of automating this coordination
between the tools.
> This, of course, is just one more step in the process of how krb5
> sources are supposed to be handled. It wouldn't be a bad idea for
> someone to write a short document defining the complete source
> maintainance procedures (ie: always list files in the ChangeLog, then
> use the ChangeLog as the CVS log entry) so that we can be sure
> everyone is doing the same thing.
Be careful of overspecifying.
For example, I've disagreed with some people sometimes on the use of
ChangeLog versus CVS log entries. E.g., for a large set of changes to
many files to implement one significant functional change, I (and
other people) will often log all the gory details in the ChangeLog
file(s), and describe the change in higher-level terms in the CVS log.
The CVS log entries are the ones getting mailed out to people; I think
that argues for a brief high-level description when appropriate rather
than 30 lines of details. And if someone running "cvs log" wants more
details they can run "cvs diff". And they probably already have the
changelog in front of them anyways.
As an example, consider merging changes between Cygnus and MIT. If
we've got a dozen big changes to appl/bsd to merge in, do you really
want 100 lines of details dropped into your mailbox, or is 10 lines
saying things like "Added expired-password changing to login.krb5;
details in ChangeLog" going to be enough?
I don't think either approach is necessarily wrong. And you can't
insist on a specific way of doing it without implicitly declaring
other ways as wrong. That's not to say that recommendations can't be
made, but they should be distinguished from specifications.
