Documentation of major changes to the ports collection

Ken Smith kensmith at cse.Buffalo.EDU
Wed Dec 3 13:35:59 UTC 2003

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. 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... :-]

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.

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.

						Ken Smith
- From there to here, from here to      |       kensmith at
  there, funny things are everywhere.   |
                      - Theodore Geisel |

More information about the freebsd-doc mailing list