Documentation of major changes to the ports collection

[Erwin Lansing]

On Wed, Dec 03, 2003 at 08:35:57AM -0500, Ken Smith wrote:
> On Wed, Dec 03, 2003 at 01:43:53PM +0100, Erwin Lansing wrote:
> 
> > As mentioned on -developers, I've taken it upon me to try and see if we,
> > the ports people, can create a document not much unlike the Release
> > Notes from our src brothers. Thoughts so far are that it should be some
> > kind of combination of /usr/src/UPDATING and relnotes, where both major
> > changes to major ports (ie. GNOME) can be announced to users and major
> > changes to ports infrastructure (ie. bsd.port.mk) can get more attention
> > of committers.
> > 
> > The first thing to decide would be which form this document should be
> > in. My first thought would be an article so we both have an online and
> > an offline version. One disadvantage of this would be that the offline
> > version would not be updating along with an update of the ports
> > collection via cvsup.
> 
> [ These are just humble thoughts, I'm not trying to discourage you
> or anything... :-]

No worries, I'm just brainstorming a bit here to try to get some input
from people who have worked with this kind of thing before.
> 
> Keep in mind the purpose of the document and who you expect to be reading
> it.  There is a reason /usr/src/UPDATING is plain text.  The target
> audience wouldn't read it if it were done as docbook markup.  The
> relnotes are *exactly* that - Release Notes designed to be accurate
> at the point the release happens.  It's also generally expected they
> would be read from the WWW site as part of an administrator starting
> to think about upgrading the systems at their site to the new release.
> They're not going to look at it in between.

Yes, I've been thinking about that.
> 
> IMHO you would be best off stealing the src folks' setup exactly as
> it is.  For ``emergency'' stuff phased in out of sync with anything
> resembling a release schedule (e.g. the change that kicked off the
> entire discussion on -developers) put it in /usr/ports/UPDATING.  The
> relnotes can be a perhaps slightly condensed list of major changes,
> new gotchas, etc. that got phased in between releases.
> 
Although I'm all that happy about starting two new documents, I keep
running into problems with how to combine the best of both worlds
and perhaps the best would be both. One plaintext UPDATING-style where
all ports-committers can add items for developers to and one relnotes-style,
which rotates at each release and is published at the website more oriented
at users.

-- 
                    _._     _,-'""`-._
Erwin Lansing      (,-.`._,'(       |\`-/|    erwin at lansing.dk
http://droso.org       `-.-' \ )-`( , o o)    erwin at FreeBSD.org
                    -bf-      `-    \`_`"'-
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20031203/f3a89732/attachment.sig>