Skip site navigation (1)Skip section navigation (2)
Date:      Sat, 28 May 2005 09:49:51 -0700
From:      "Bruce A. Mah" <bmah@freebsd.org>
To:        "Simon L. Nielsen" <simon@freebsd.org>
Cc:        bmah@freebsd.org, cvs-doc@freebsd.org, Peter Jeremy <PeterJeremy@optushome.com.au>, Hiroki Sato <hrs@freebsd.org>, cvs-all@freebsd.org, doc-committers@freebsd.org
Subject:   Re: cvs commit: www/en/releases/5.4R errata.html
Message-ID:  <1117298991.46625.33.camel@tomcat.kitchenlab.org>
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>

next in thread | previous in thread | raw e-mail | index | archive | help

--=-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--



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?1117298991.46625.33.camel>