Thoughts on how to structure the release notes...

[Edward C. Bailey]

>>>>> "Toshio" == Toshio  <toshio at tiki-lounge.com> writes:
...
Toshio> I like the idea of more structure.  I don't know if I agree with
Toshio> using comps.xml for groups, though.
...
Toshio> So I would like groups based on changes to the distro rather than
Toshio> groups based on lists of programs. (Ie: selinux group w/
Toshio> description of selinux and how packages have changed/been added to
Toshio> make this work.)

Yes, this would be very nice.  I'd note, however, that many of the types of
entries that have been put in the release notes in the past have been
"one-offs" -- to use your example, there might only be one short blurb
about a change to SELinux, and no other SELinux-related stuff.  So the
possibility exists for release notes with many sections, most of which are
one entry in length.  Not that useful... :-)

Of course, the two counter-examples to this are Anaconda and the kernel; As
it turns out, Anaconda is the sole occupant of the "Supported Packages"
group (yeah, I don't know what that name is supposed to mean, either), and
the kernel is part of the "Core" group (which contains ~40 other packages,
most of which I've never written about in the release notes).

So although this approach is different from the one you've described, the
effect may end up being quite close to what you're asking for... :-)

Toshio> That might be a lot more work though as it requires a human to
Toshio> decide what the overall themes are and construct how those themes
Toshio> fit with the changes in the features of indiidual packages.

Bingo! You've hit on the exact reason I'm not going to do it that way! :-)
The problem is that the content for the release notes comes to me in dribs
and drabs -- never all at once.  This makes is difficult to come up with a
structure (other than "mechanically" -- like basing the structure on
package groups) that makes sense.

Add to this the fact that the release notes are *always* undergoing
last-minute -- er, make that last-second -- changes, and you can see that
the effort to come up with a nicely thought-out structure is too great, and
the time in which to do it is too small.

Toshio> If a package-based scheme is adopted, I think the groups should be
Toshio> thought out a little more. 

Well, I have absolutely no control over that, so if you want to see a
change in the package groups, it's time to talk it up on the list and hope
the right developers see it. :-)

Toshio> Even though the release notes are a flat file, there should be a
Toshio> hierarchy to it (So emacs, xemacs, and editors can be together;
Toshio> development tools and ruby; etc) If a group has too many worthy
Toshio> changes, then subsections can be broken out.  If not, then keep the
Toshio> changes together so the grouping reduces the number of things I'm
Toshio> thinking about rather than increases it.

The way the release notes are displayed in Anaconda limits what I can do as
far as the hierarchy is concerned.  The HTML rendering widget used is
pretty primitive, so a single-level hierarchy is pretty much the best we
can shoot for.

Toshio> Once again, just my two cents.  I'm sure I'll find useful whatever
Toshio> format is produced.

Thanks -- hopefully you won't be disappointed... :-)

                            Ed
-- 
Ed Bailey        Red Hat, Inc.          http://www.redhat.com/