From owner-freebsd-doc@FreeBSD.ORG Wed Dec 3 05:35:59 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 C9D8A16A4CE for ; Wed, 3 Dec 2003 05:35:59 -0800 (PST) Received: from electra.cse.Buffalo.EDU (electra.cse.Buffalo.EDU [128.205.32.2]) by mx1.FreeBSD.org (Postfix) with ESMTP id 9955A43F75 for ; Wed, 3 Dec 2003 05:35:58 -0800 (PST) (envelope-from kensmith@cse.Buffalo.EDU) Received: from electra.cse.Buffalo.EDU (kensmith@localhost [127.0.0.1]) hB3DZwus023476 for ; Wed, 3 Dec 2003 08:35:58 -0500 (EST) Received: (from kensmith@localhost) by electra.cse.Buffalo.EDU (8.12.10/8.12.9/Submit) id hB3DZwIx023475 for doc@FreeBSD.org; Wed, 3 Dec 2003 08:35:58 -0500 (EST) Date: Wed, 3 Dec 2003 08:35:57 -0500 From: Ken Smith To: doc@FreeBSD.org Message-ID: <20031203133557.GA23226@electra.cse.Buffalo.EDU> References: <20031203124353.GD82966@droso.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20031203124353.GD82966@droso.net> User-Agent: Mutt/1.4.1i 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 13:35:59 -0000 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... :-] 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@cse.buffalo.edu there, funny things are everywhere. | - Theodore Geisel |