[csw-maintainers] Need for additional documentation

[Dagobert Michelsen]

Hi Jeffery,

Am 06.08.2010 um 21:48 schrieb Jeffery Small:
> I have been using a very old, locally compiled version of mutt for  
> the past
> few years because I could never get the CSW version of mutt to work  
> with
> my predefined macros and key bindings in my muttrc file, and just  
> didn't
> have the time to devote to tracking down the problem.  However,  
> today I bit
> the bullet and discovered a great surprise; the CSW mutt binary was  
> a link
> pointing to another link back in /etc/opt/csw/alternatives which was  
> using
> a slang-compiled version of mutt!  Once I relinked to the ncurses  
> version
> of mutt, everything worked just fine!
>
> The point of my story is that I didn't even have any idea that these
> alternate versions existed and knew nothing about the "alternatives"
> directory.  I keep running across little tricks like this regarding  
> CSW
> software packages which would should have been configured at  
> installation
> time had I known about them.  Now, maybe there is some note that  
> displays
> regarding this during a mutt installation or upgrade,

In fact there is after package installation :-)

> but even if that
> were so, we all know that none of these messages can be seen during a
> typical install/upgrade if the automatic configuration parameters  
> are set.
> Everything just scrolls off the screen much too fast to monitor it.

True.

> For some packages, there are very important steps that need to be done
> during an installation or checked after an upgrade and this  
> information
> needs to be placed in some well known location where every user can  
> review
> it.  When I was compiling packages under the old system, I used to  
> include
> this information in on the webpage for the packager in the News (I  
> think
> that was what it was called) section.  There really ought to me a  
> "Special
> Instructions" section added to the current web page which just has  
> this
> important information, like tweaking configuration files, starting  
> services,
> selection between alternatives, etc.
>
> But I would take this a step further.  If these notes were packaged  
> up into
> a file shipped with each package, then the CSW install program could  
> copy
> this content to a new temporary file during the installation or  
> upgrade
> process, along with any error or warning messages that occurred, and  
> then
> display this information to the user for their review after they were
> done.  This would allow a major install or upgrade to occur  
> unattended,
> with only a need to review the important information immediately after
> completion.  This would be extremely helpful to people installing new
> CSW packages, since they would get these pointers on how to properly
> configure the packages in real time without having to hunt through  
> volumes
> of documentation for answers to questions that they probably don't  
> even
> know to ask.
>
> I'm not suggesting duplicating a package's documentation here.  Just a
> short file with important tips that the packager knows are important  
> for
> proper use of the software.  In my case, I was using mutt long  
> before the
> the slang/curses split, and it never occurred to me to think that  
> there was
> even an issue like this to be investigated.
>
> Just some friendly feedback for your consideration! :-)

There is obviously some lack of visibility here as you noted correctly.

Some notes:
1. Some maintainer already maintain a Changelog per package. The  
standard location is
     /opt/csw/share/doc/<catalogname>/Changelog
2. There may be some standard on the format of the Changelog, but it  
may be
    difficult to extract specific information
3. It would be nice if checkpkg could somehow verify that the  
Changelog is there
    and has been updated after the previous package release
4. The changes should be printed on package update and/or stored in an  
update-log.

Regarding 3: checkpkg could verify the existence of Changelog and see  
that the
Changelog provided by the new package only has information prepended.

Regarding 4: On package upgrade there could be a hook for pkgutil  
making a diff
of the existing Changelog and the Changelog of the package to be  
installed and
either print the diff or store it in a "system upgrade log" for this  
upgrade operation.

Additionally, on GAR package creation there could be an automatic  
addition to the
Changelog shipped in the package that a packagerelease occured with  
the timestamp
of the package. However, this information must then go back to the  
repository.
On package rejection on release this would lead to superflous release  
tags in
the Changelog. It would be ideal if rejection of a specific package  
release would
also be noted in the Changelog. However, that would require a much  
more integrated
release process making use of CSWREPO inside the package to fix the  
files/Changelog
of the exact package description. But I see no reason why we can't  
start with 1-4
right now.


Best regards

   -- Dago