Date: Thu, 25 Apr 2002 08:44:51 -0700 From: bmah@FreeBSD.org (Bruce A. Mah) To: "Karsten W. Rohrbach" <karsten@rohrbach.de> Cc: "Bruce A. Mah" <bmah@FreeBSD.org>, Doug Barton <DougB@FreeBSD.org>, JJ Behrens <jj@nttmcl.com>, freebsd-stable@FreeBSD.org Subject: Release notes (was Re: *** HEAD'S UP ***) Message-ID: <200204251544.g3PFipCV075997@intruder.bmah.org> In-Reply-To: <20020425152543.A13500@mail.webmonster.de> References: <20020422114407.B21612@alicia.nttmcl.com> <20020423215717.S66402-100000@master.gorean.org> <20020424125400.F87244@mail.webmonster.de> <200204241304.g3OD4slv062649@intruder.bmah.org> <20020425152543.A13500@mail.webmonster.de>
next in thread | previous in thread | raw e-mail | index | archive | help
If memory serves me right, "Karsten W. Rohrbach" wrote: > i have never seen some bits from the relnotes display while making > installword or executing mergemaster. the main idea here is to provide > the important aspects of release notes to people that just read how to > update (makeworld/mergemaster standard invocations) and start wondering > about things having changed, going to the mailing list and getting the > info from other users on how to find release notes for an uninstalled > base dist and being told to read the UPDATING. with proper automation > this would make things easier and produce less trouble for the > non-gurus. Hi Karsten-- Noted. Doing this in a totally automated way isn't feasible (IMHO), for reasons I'll explain below. > > src/release/doc/* > > http://people.freebsd.org/~bmah/relnotes/ > > i know, bruce, but that was not my point. > generation of the docs requires the doctools me[tg]aport, which is not > installed on every firewall and smaller server due to obvious reasons ;-) I wasn't suggesting putting the doctools metaport everywhere, and I'm sure you know that. If you look at the *second* line you quoted, that's a pointer to one of two places on the net for the already-rendered release documentation. Nothing needed except for a Web browser. > you know how to make the docs, i know how to generate them, but does a > newbie who just got the cd set and upgrades the system know it?=20 Man, this is the *easy* case! Every CDROM, for as long as I can remember, has had the release notes (in text) in the *top level directory*. Since 4.4-RELEASE, we started putting HTML as well. snapshots.jp.freebsd.org adds PDF for their snapshot ISOs. You can even read these from sysinstall's documentation menu. In addition, the announcement for every release, as well as the main Web site, has a pointer to the on-line version of the release notes. > > This information is in UPDATING. I suppose one could make a credible > > root@WM:datasink[/usr/src]3# grep SA UPDATING=20 > - MSA port (587) turned on by default > root@WM:datasink[/usr/src]4# grep '$FreeBSD:' UPDATING=20 > $FreeBSD: src/UPDATING,v 1.73.2.62 2002/04/21 22:33:06 dougb Exp $ > > no, the information is not in updating. You're right. They mention the changes that took place but not the actual SA numbers. Actually, I think our SO team may have gotten the hint, because I just saw a commit to UPDATING that added a reference to SA-02:23. I bet if we ask real nicely, we can get them to add references to the other SAs as well. > > argument that it should be in the release notes for the security > > branches (e.g. RELENG_4_5), but that's not the way we do things > > currently. > > i know, that's why i brought up this issue for discussion. I haven't figured out what's the right way to maintain release notes for the security branches. I'm not sure if I have the time or energy to do this either. > errh, btw: > root@WM:datasink[/usr/src]5# grep '$FreeBSD:' README =20 > $FreeBSD: src/README,v 1.15.2.3 2000/10/27 16:14:34 asmodai Exp $ > > the readme tells about synching, kernel config, what the subdirectories > contain, and that's about it. it would make sense to lead a newbie to > either the online docs or to an already generated ascii version of the > relnotes of the release he's actually going to install. just a thought. Can we just point people to the Handbook? I know it's a cop-out but pointers get stale less quickly than text does. Independent of that...I haven't looked at the appropriate part of the Handbook lately, but we can probably add a couple paragraphs about where to go for release notes and errata, if they are not there already. > i know, there's a chicken-and-egg problem in here, and i can't come up > with an automated solution for it, since i am not the keeper of the > docs. do you generate your relnotes web page automatically? I feel like I'm repeating myself. I update my snapshot page manually, as a part of testing each of my commits. So it tracks *my* commits closely and it tracks *other people's* commits to within a few days. The copy on the FreeBSD Web site is updated automatically every 6 hours but only provides HTML. > could you > somehow check the release notes into the corresponding branches on an > automated basis? No. Think of all the deltas that would bloat the repository. > it would be really a Good Thing[tm] to have > http://people.freebsd.org/~bmah/relnotes/4.5-RELEASE/relnotes-i386.txt > in /usr/src/RELNOTES for 4.5 based systems, for example, because > - it is available locally > - it is already compiled to ascii > - /usr/src/RELNOTES is a very prominent spot which can be found even by > someone totally new to freebsd You can already get this stuff from the Web site. I'm already satisfied with the visibility of release notes for the people who are installing RELEASE versions. For the people who are doing source upgrades, there's the two Web versions, plus the option of building the release documentation from scratch. If someone wants more details than this, he/she can always subscribe to cvs-all and read the commit messages. You (and perhaps many other people) seem to be making the assumption that the release notes perfectly reflect the state of the src/ tree. They don't. The best synchronization between the release notes and reality comes, not surprisingly, on the day of a RELEASE. As an example, I did commits yesterday that documented changes in RELENG_4 that were two weeks old. Some of *those* hadn't been documented in HEAD yet...the oldest was over a month old. And I'm not anywhere near finished with my backlog of committer mail! I'm not opposed to the idea of more visibility of the release notes. And I know they're not perfect. What I'm saying is that almost all the ideas that have been proposed over the past 12 months or so have either implied much additional work on my part or undesirable engineering choices. Cheers, Bruce. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-stable" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200204251544.g3PFipCV075997>