Date: Wed, 3 Dec 2003 16:09:58 +0100 From: Erwin Lansing <erwin@FreeBSD.org> To: doc@FreeBSD.org Subject: Re: Documentation of major changes to the ports collection Message-ID: <20031203150958.GC72102@droso.net> In-Reply-To: <20031203133557.GA23226@electra.cse.Buffalo.EDU> References: <20031203124353.GD82966@droso.net> <20031203133557.GA23226@electra.cse.Buffalo.EDU>
next in thread | previous in thread | raw e-mail | index | archive | help
--S1BNGpv0yoYahz37
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable
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:
>=20
> > 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.
> >=20
> > 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.
>=20
> [ 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.
>=20
> 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.
>=20
> 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.
>=20
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.
--=20
_._ _,-'""`-._
Erwin Lansing (,-.`._,'( |\`-/| erwin@lansing.dk
http://droso.org `-.-' \ )-`( , o o) erwin@FreeBSD.org
-bf- `- \`_`"'-
--S1BNGpv0yoYahz37
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (FreeBSD)
iD8DBQE/zfzGqy9aWxUlaZARAq/CAKCIY9oGJk4ac/DEM316X9tEAD4+6ACfQ81K
OCy33/FU+M46ZA+KzJC7ruA=
=I/Bp
-----END PGP SIGNATURE-----
--S1BNGpv0yoYahz37--
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20031203150958.GC72102>