[gentoo-dev] Re: Changelogs

[Duncan]

Georgi Georgiev posted <20050727022212.GB10581@××××××××.net>, excerpted
below,  on Wed, 27 Jul 2005 11:22:12 +0900:

> maillog: 26/07/2005-22:05:49(-0400): Alec Warner types
>>
> ... skip some text that I mostly agree with...
>>
>>
> I mentioned this before, but it would be nice to somehow mark important
> messages in the changelog. Prefix them with something, say "WARNING around
> there", anything, as long as it is agreed upon and everybody uses it.
> Changelogs are huge and even if portage is not made to show only the
> relevant *important* information, it would be nice to have an easy way to
> see it by grepping the output of emerge -l.

Note that most of the previously mentioned "stable on foo, bug #000000"
entries relate to one of two things.  (1) A security bugfix (the majority
of the cases). (2) A specific request to stabilize the package, either
from the package maintainer to the archs (so the maintainer can remove old
versions without removing the latest stable for arch foo), or from users
reporting stability of a ~ package and no bugs for 30 days, thus
requesting a nudge to stable.

Thus, it's generally safe (from my experience) to skip-over further
investigation of these entries.  On critical packages, however, I'll look
into all the "fix for #000000" type entries.

Generally, however, the biggest compatibility issues will be on "version
bump" type entries.  It's important to realize, however, just what the
Gentoo changelogs (as opposed to the upstream changelogs) document --
Gentoo, that is, primarily ebuild, changes.  A version bump is often a
trivial change in terms of the ebuild and where Gentoo is concerned, even
where it's a HUGE change in terms of configuration and upstream. 
Therefore, the Gentoo changelog contains the information it should, simply
noting the version bump.  If the package is critical and you are on a
mission critical machine that you can't afford to have down for a few
hours while you straighten things out, every time you see a "version bump"
Gentoo changelog entry, it's a flag meaning "go and checkout the upstream
changelog, if you care about the smooth operation of your machine!"

Now, granted, if the Gentoo devs know about a particular config change
that could mess things up, putting that in the Gentoo changelog can be a
good thing, and actually, it seems to me that Gentoo devs ARE fairly good
about this.  Where they know there will be issues, they document them both
in the changelog, and for big ones, often by creating upgrade guides and
the like, and by posting notices on the Gentoo front page and in GWN. 
However, that in no way means they /have/ to do such things.  A
responsible sysadmin (which hopefully means every Gentoo user doing
upgrades, they being the sysadmins on their systems) WILL checkout version
bump info, if it's a mission critical application on a mission critical
machine.

Note that I don't always do so here, but that's because computing is a
hobby for me, not a job, I'm running ~arch and occasionally unmasking
stuff that's hard masked for testing, so I too can test it, and I
expect not entirely smooth upgrades from time to time.  I do basic due
diligence checking changelogs and keeping up with the general state of
things on packages I consider critical, but don't worry too much about
individual upgrades causing issues, since it's not a problem for me to
reboot, if necessary to a rescue partition, and/or spend an hour or two
fixing things, should they break.

There are, however, two issues with changelogs that DO frustrate me.

1) I like to know exactly what's behind any of those [ UD] things that
come up occasionally, the "forced" downgrades.  emerge -pl doesn't work
for those, and I wish it did.  I have to manually view the changelog,
typing in the specific path to it in the portage tree in ordered to do so,
to see what's up in these types of cases.  It'd be very nice to have
portage's changelog viewing functionality take negative ranges as well,
since that's effectively what's happening here.  This issue has of course
been raised before and the feature may get into a future version of
portage, but it may be awhile.

2) I get frustrated with the changelog for portage itself.  Again, keeping
in mind the purpose of the portage tree changelogs, to document ebuild
changes, not upstream code changes, not having a working portage tree
changelog for portage itself does make some sense, given the fact that
it's a Gentoo project and thus that we ARE the upstream.  However, the
fact remains, there exists no easy way to access perhaps VERY vital
change documentation, without first merging the upgrade to get the
changelog in /usr/share/doc/portage-xxxx/.  Yes, one can use -p, see
portage is on the list, do a fetch, then manually extract the changelog
and see what's up, or one can visit the website and check it out there,
but for such a critical part of a Gentoo machine's infrastructure, one
would certainly wish for something a bit easier than either of these. 
baselayout and udev, among other Gentoo or semi-Gentoo developed packages,
manage decent in-tree logs, why can't portage do so as well?

Maybe what's needed to address #2 is simply to include a separate portage
changelog file, somewhere within the tree, possibly as its own package, or
in the profiles root dir, along with the global package.mask, and use.desc
and use.local.desc files.  Portage could then add an "emerge portinfo"
function, similar to "emerge info", that would spit out the "upstream"
changelog between what's currently installed, and any new version.

Expanding on the idea a bit further, what about creating a generic "emerge
changelog" function, that fetches the tarball if necessary, then extracts
only the changelog, and opens it for viewing (presumably using the $PAGER
environmental variable to determine what to display it with)?  Naturally,
given Gentoo can't control the upstream changelog format, enforcing
parseability rules as it does for its own, the entire changelog would of
necessity be displayed, leaving the user to figure out the relevant
cutoffs instead of doing it automatically as emerge -pl does with the
portage tree changelogs, but it'd still be a rather easier way to view
upstream changelogs before installation (or for that matter, after) than
we have now.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman in
http://www.linuxdevcenter.com/pub/a/linux/2004/12/22/rms_interview.html


-- 
gentoo-dev@g.o mailing list