From owner-freebsd-doc@FreeBSD.ORG Wed Dec 3 07:10:01 2003 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 8230216A4CE for ; Wed, 3 Dec 2003 07:10:01 -0800 (PST) Received: from mail.droso.net (koala.droso.net [193.162.142.74]) by mx1.FreeBSD.org (Postfix) with ESMTP id 320BD43F75 for ; Wed, 3 Dec 2003 07:10:00 -0800 (PST) (envelope-from erwin@mail.droso.net) Received: by mail.droso.net (Postfix, from userid 1001) id 29C2122858; Wed, 3 Dec 2003 16:09:58 +0100 (CET) Date: Wed, 3 Dec 2003 16:09:58 +0100 From: Erwin Lansing To: doc@FreeBSD.org Message-ID: <20031203150958.GC72102@droso.net> Mail-Followup-To: doc@FreeBSD.org References: <20031203124353.GD82966@droso.net> <20031203133557.GA23226@electra.cse.Buffalo.EDU> Mime-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="S1BNGpv0yoYahz37" Content-Disposition: inline In-Reply-To: <20031203133557.GA23226@electra.cse.Buffalo.EDU> User-Agent: Mutt/1.4.1i X-Operating-System: FreeBSD/i386 5.1-CURRENT Subject: Re: Documentation of major changes to the ports collection X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 03 Dec 2003 15:10:01 -0000 --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--