Thoughts on how to structure the release notes...

[Toshio]

On Wed, 2004-02-18 at 14:28, Edward C. Bailey wrote:
> >>>>> "Toshio" == Toshio  <toshio at tiki-lounge.com> writes:
> 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... :-)
> 
I don't want small one-off groups.  The SELinux group would talk about
all the bits and pieces of all the packages that had to be modified to
make the change happen.  Like you say though, this is a lot^H^H^H^H^H
too much work.

> 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. :-)
> 
I think that the use case of a software installer versus informational
reading is different enough that the comps.xml file can be fine for the
installer and inappropriate for the release notes.  That said, I think
the comps.xml file can be a very good starting place.  It just needs
some simple adjustments like condensing several of the comps.xml groups
into one meta-group.

When you talk about not including a group if there's nothing to say
about it, that's good, but in my view, there shouldn't be a group if
there's not at least three entries in it.  (Maybe I did too many
outlines in grade school:-)  But the information should still be in the
release notes.  So the information has to be promoted up a level to find
a metagroup with enough information in it to justify its existence.

> 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.
> 
I don't need hypertext links and all that, but can't we do something
like this:
<h#>Editors:</h#>
* Emacs
  o An Emacs nifty new feature
  o An Elisp nifty new feature
  o A new wanderlust feature
* XEmacs
  o yadda yadda yadda
  0 yadda-yadda 2
* Vim
<h#>Desktop Environments</h#>
* Gnome
  o ...
  o ...
  o ...
* KDE
* XFCE
<h#>Network servers</h#>
* imap
* web server
  o mod_ssl
  o tux
  o mod_python
* samba

If there's a lot to say about a component, then add more entries
underneath.  If there really isn't then leave it all at the next higher
level.

I need more organization to help my brain remember all the changes in
the distribution.  Even a shallow hierarchy like this makes it possible
to remember a lot more detail.
-Toshio
-- 
Toshio <toshio at tiki-lounge.com>