[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: ChangeLog format

On Sun, 22 Oct 1995, Ian Jackson wrote:

> There are two things here: the Changelog format and the announcement
> format.  I think it is probably valuable to separate them.

Yes.  I've been following a practice of cutting my most recent
ChangeLog entry out and using it verbatim in the package announcement.
Occasionally, I'll put some additional info in the ChangeLog and
just cut the final portion of the final entry for the announcement.
When I went to the dchanges(1) format, I went to that format in
the ChangeLog as well (the Priority and Changes fields are there).

> The announcements should contain the Changelog entries since the last
> announced version, and they also need to contain the MD5 checksums,
> filenames and file sizes.

This gets a bit specific to the working style I've developed, but
it might be useful to discuss it.  Others might find it useful,
or I might pick up something useful from reactions.

       doit (a badly-named package building script)
       sendlist (for kermit: "take sendlist")
       <package>-<version>/ (several of these)
         <package>-<version>-<revision>.{*.gz, *.deb} (latest ones)
         old/ (old .gz and .deb files)
         changes (announcement stuff cut from most recent ChangeLog)
         <package>-<version>.orig/ (upstream sources)
         <package>-<version>/ (debian working directory)

The doit script builds one or more packages for distribution.
It checks that the changes file is more recent than the package
ChangeLog file, builds the package, symlinks .gz and .deb
filenames to files in the <package>-<version> directory,
runs "dchanges -n -c <package>-<version>/changes <file_list>"
to produce <package>-<version>-<revision>.changes, and appends
names of the package files and the changes file to sendlist.
The dchanges program puts md5sums, sizes, etc. into the
<package>-<version>-<revision>.changes file for me.

All this is a bit structured for maintainers with just a few
packages, but I've got about 20.

> The Changelog (for a package or the distribution) will contain all the
> relevant Changelog entries, but no filenames &c.

I've got some misgivings about mandating stuff like this.  It seems
to be getting a bit deep into micro-managing how individual maintainers
go about doing their source package housekeeping.

I recognize the value in having everybody do this the same way,
but we (the whole team of maintainers) have not been very successful
in managing to do things which have a visible impact on the
distribution in a completely consistent manner.  Compliance (or not)
with this would be invisible, unless someone took on the job of
ChangeLog Policeman and nagged violators.

Actually, I'd be one of the violaters nagged in any case.
I'm not keeping separate ChangeLog files in my debian source
packages (I tried it for a while, and dropped it).  I'm
appending ChangeLog info to the debian.README file.  My
packages generally only add files named debian.something
to the upstream sources, and seek to minimize changes to
upstream source files.  Debianizing a new upstream release
is usually pretty easy -- copying debian.* from the current
package and editing debian.rules and debian.README generally
does most of what needs doing.  Aside from the added debian.*
files, there's usually little or no difference between my
source packages and the upstream sources.

Is the name "ChangeLog" and the format you favor an emacs thing?
I'm not an emacs person, and wouldn't know about emacs-isms.

> Regarding the delays between announcements on debian-changes and
> packages' appearance in the distribution directories:
> I find it very useful to have information about packages which are on
> their way to Incoming - this means I can grab them out of there (when
> they're completely uploaded) without having to wait for anyone to
> move packages or make announcements.
> This can also be important for programs with security problems or
> other urgent bugfixes.

But I don't think it's useful to have packages announced to the
world at large several days before they show up, and less useful
to have packages announced which never do show up.  Perhaps we
could use (yet)another mailing list for this, with mechanized
announcements from debian.org of new packages seen in Incoming.

> We shouldn't just move packages automatically out of incoming, because
> this would make us far too vulnerable to random people uploading bogus
> stuff, so this delay can't be eliminated.

Right, but announcing them before they're available is questionable,
and announcing packages which never show up moreso.

> The conclusion I come to is that there should be at least two lists -
> one which announces the packages when they're released by the
> maintainer (and which perhaps has an automatically-generated report
> from the FTP site maintainer when packages are moved), and one which
> announces them as they are moved into view.

That's pretty much the conclusion I came to as well.

> Note that none of what I'm saying above means that we need a horrible
> un-human-readable changelog or announcement format at any stage.  My
> format is perfectly machine-readable.  If people want me to write
> scripts to parse my changelog entries and release announcements I'd be
> only too happy to do so, or to document my format so that they can doo
> it.

Horrible, etc. seems a bit harsh.  I'm not rabid about the dchanges
format (which, after all, wasn't my idea in the first place), but I
don't think it's all that bad.  I think having the dchanges tool
available to syntax check it before uploading is a big plus if
it's supposed to be machine-parsed after uploading.  If the group
wants to go to some other format, and someone is willing to field,
document, and maintain a tool to support building and syntax-checking
package announcements using that format, I'll retire dchanges(1) and
switch with little or no complaint.

Reply to: