From owner-cvs-doc@FreeBSD.ORG Sat May 28 17:03:04 2005 Return-Path: X-Original-To: cvs-doc@freebsd.org Delivered-To: cvs-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 4045916A41C; Sat, 28 May 2005 17:02:56 +0000 (GMT) (envelope-from bmah@freebsd.org) Received: from b.mail.sonic.net (b.mail.sonic.net [64.142.19.5]) by mx1.FreeBSD.org (Postfix) with ESMTP id 3E95343F90; Sat, 28 May 2005 16:49:53 +0000 (GMT) (envelope-from bmah@freebsd.org) Received: from tomcat.kitchenlab.org (tomcat.kitchenlab.org [64.142.31.107]) by b.mail.sonic.net (8.13.3/8.13.3) with ESMTP id j4SGnquV014043 (version=TLSv1/SSLv3 cipher=EDH-RSA-DES-CBC3-SHA bits=168 verify=NO); Sat, 28 May 2005 09:49:53 -0700 Received: from tomcat.kitchenlab.org (localhost.kitchenlab.org [127.0.0.1]) by tomcat.kitchenlab.org (8.13.3/8.13.1) with ESMTP id j4SGnqxJ047408; Sat, 28 May 2005 09:49:52 -0700 (PDT) (envelope-from bmah@freebsd.org) Received: (from bmah@localhost) by tomcat.kitchenlab.org (8.13.3/8.13.1/Submit) id j4SGnqKv047407; Sat, 28 May 2005 09:49:52 -0700 (PDT) (envelope-from bmah@freebsd.org) X-Authentication-Warning: tomcat.kitchenlab.org: bmah set sender to bmah@freebsd.org using -f From: "Bruce A. Mah" To: "Simon L. Nielsen" In-Reply-To: <20050528082910.GH787@zaphod.nitro.dk> References: <200505261456.j4QEuh7s088699@repoman.freebsd.org> <1117119937.34783.14.camel@tomcat.kitchenlab.org> <20050526191549.GB17267@cirb503493.alcatel.com.au> <20050526193032.GE794@zaphod.nitro.dk> <1117258487.764.14.camel@localhost> <20050528082910.GH787@zaphod.nitro.dk> Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="=-CTbYYyHn/KTAGLUh2LLo" Date: Sat, 28 May 2005 09:49:51 -0700 Message-Id: <1117298991.46625.33.camel@tomcat.kitchenlab.org> Mime-Version: 1.0 X-Mailer: Evolution 2.2.2 FreeBSD GNOME Team Port Cc: bmah@freebsd.org, cvs-doc@freebsd.org, Peter Jeremy , Hiroki Sato , cvs-all@freebsd.org, doc-committers@freebsd.org Subject: Re: cvs commit: www/en/releases/5.4R errata.html X-BeenThere: cvs-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: CVS commit messages for the doc and www trees List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 28 May 2005 17:03:04 -0000 --=-CTbYYyHn/KTAGLUh2LLo Content-Type: text/plain Content-Transfer-Encoding: quoted-printable If memory serves me right, Simon L. Nielsen wrote: > [I just added hrs@ to CC, since this is also his area] Good idea. > Well, basically I see three ways to go: >=20 > 1. Status-quo, which means that errata will likely be more or less > out-of-date (hopefully less). It takes a bit of commitment on the part of someone working on the release documentation to keep it "less out of date". When I "owned" the release documentation, I was pretty proud of getting security advisories propagated to the errata and release notes within a few hours of them showing up on announce@. Sometimes, security-officer@ helped by giving me a sneak peak at an advisory. > 2. Just link to the advisory and have no description, or a very brief > one of where there problem lies, so it can be written in a very short > time and is therefor more likely to be written by a security-team@ > memeber during the advisory release cycle. I think someone suggested a simple link before...I objected to this on the grounds that the link gives almost no information as to whether someone should bother looking up the advisory. However, I just reread the past few advisories issued by security-team@ and the "Topic" of each advisory is actually a pretty good "brief description", which we could probably use. > 3. Simply copy/paste the relevant part of the security advisory > (probably the "Problem Description" and "Impact" sections) and use > that. This has the writing style mismatch problem that we discussed earlier. > I would probably prefer 2, with an appropriate header in the section > basically telling people to read the advisories. OK. How about something like the following paragraph and table (pretend there is some real DocBook markup in here and don't worry too much about the wording): -----8<----- The following security advisories pertain to FreeBSD 5.4-RELEASE. For more information, consult the individual advisories. Advisory Date Topic -------- ---- ----- FreeBSD-SA-05:09.htt 13 May 2005 information disclosure when using HTT FreeBSD-SA-05:08.kmem 6 May 2005 Local kernel memory disclosure FreeBSD-SA-05.07.ldt 6 May 2005 Local kernel memory disclosure in i386_get_= ldt ... -----8<----- The nice thing about this table is that security-team@ doesn't need to worry about writing a single grammatically correct sentence (or two) to describe each issue, other than making sure that the initial word of each topic is capitalized consistently (hint hint). :-) > > Basically this meant understanding the advisory well enough to write a > > one-sentence summary of it. I usually got it right, although there was > > once when it took many iterations between security-team@ and me before > > the correct text finally made it into the errata. I'm not sure if ther= e > > are any shortcuts other than someone (whether on security-team@, re@, o= r > > other) just sitting down and writing some suitable text. >=20 > For most advisories I currently know the issue well enough to describe > it, but the problem is that it takes me forever to do rephrasing into > something which fits the errata wording style, and is at least > somewhat grammatically correct :-/. >=20 > The same issue goes for the Release Notes btw. Right...I think we both understood this but didn't state it explicitly. One problem with the table approach above is the case of MD advisories (such as SA-05:09.htt). Because we (currently) generate a different release notes document for each architecture. The method I devised for doing conditional text inclusion might not work inside a table. That's OK...I'm starting to think that having separate MD release notes wasn't such a great idea to begin with; a single MI document with annotations for the few items that are MD might be better. But that's a different issue. I suggest that if we adopt the above approach we just pretend every advisory is MI and just include it regardless of architecture. A related point: The errata document for (for example) 5.3 was maintained on the RELENG_5 branch (and not RELENG_5_3). So right before we branched for 5.4, the 5.3 errata content was purged. Thus, users tracking the 5.3 security fix branch can't count on the errata document being current anymore; they have to go to RELENG_5_3 src/UPDATING to get this information. (It's worked this way all the way back to 4.3-RELEASE. Curiously, nobody has complained to me about it in the past four years. I can't remember why I set it up this way.) Bruce. --=-CTbYYyHn/KTAGLUh2LLo Content-Type: application/pgp-signature; name=signature.asc Content-Description: This is a digitally signed message part -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.1 (FreeBSD) iD8DBQBCmKEv2MoxcVugUsMRAn3VAKC3a+IPJP86NH9Rq2+3AlX5OdwCEACfTCoq tykq8Kv9n8MOgNjSIHcNx9Y= =RcaA -----END PGP SIGNATURE----- --=-CTbYYyHn/KTAGLUh2LLo--