Archive for June, 2006

Proofreading pass, Parallels

Tuesday, June 20th, 2006

Every so often, it seems like I need to make a pass through the release notes and clean up things, do some proofreading, and consolidate items. I’m doing that now, but unfortunately it’s going to be split up over about a week because I don’t seem to have any large chunks of “FreeBSD time” at the moment. It’ll get done eventually.

I finally have a machine running CURRENT…something I haven’t done since around 5.0. I’m running this inside Parallels on my Mac Mini. As a tip, selecting a machine type of “FreeBSD 5.X” seems to work just fine for 7.0-CURRENT (and very briefly for 6.1-RELEASE). Having virtualized machines like this is Very Cool.

Random thoughts on release documentation

Monday, June 12th, 2006

I’ve been doing a few minor updates to the release notes the past week
or two. This isn’t necessarily really exciting stuff (writing the
updates I mean…the stuff they describe really is pretty cool). But I
like doing updates more-or-less as they happen, so I don’t end up
having to do a whole lot of writing during the release cycle.

The other way to approach the release notes is to save everything for
the end. The advantage of doing this is that you can see the context
for everything that happened during the release cycle. The downside,
of course, is that typically things get a little hectic in the stages
of the release. hrs@ prefers this approach, I’ve seen. I think it’s a
matter of preference.

I’ve been thinking of a couple changes I’d like to make to the release
documentation. The main one is to consolidate all of the
machine-dependent (MD) documents, so that there’s only one version of
the release notes (for example) that has annotations to call out
architecture-specific items. Originally I patterned the structure of
the release notes and hardware notes after a couple of text documents
that were maintained separately for the (then) two supported
architectures, i386 and alpha. This doesn’t necessarily scale very
well to the 5-6 architectures we now support!

I writing a quick-start installer guide a year or two ago that
combined all of the MD information; I found it was a lot easier to
edit than the multiple MD documents, mostly because I could print out
a single document with all the text. At some point I’d like to finish
off the quick-start guide, or if that’s not possible, hand it off for
someone else to finish.

So many things to do, so little time…

Speaking of which, I just checked the RE schedule…we’re only about
six weeks away from the start of the 6.2 release cycle!

Security advisories, errata

Thursday, June 1st, 2006

As I’m sure many people are aware, the security team released two advisories today (they’re visible on the main FreeBSD site). The timing of some of this stuff forced us (re@) to hand-over RELENG_5_5 to the security team a little faster than we might have otherwise (so they could deal with patches for that branch). We try to cooperate as much as we can with secteam@, and in turn they give us hints about upcoming issues that might affect a release we’re working on. So it’s all good.

It’s been awhile since I had to deal with an advisory (SA-06:16 in particular) that affected four codelines (HEAD, RELENG_6, RELENG_5, and RELENG_4). So that was changes to four release notes and three errata files, plus some Web site updates. That’s a lot to do in a short time (admittedly a self-imposed deadline), but that’s probably nothing compared to the behind-the-scenes work that secteam@ had to do in order to devise and test the fixes (on over ten codelines, worst-case). So my hat’s off to them, as always.

The PDF output for the errata, specifically the table describing the security advisories, is unbelievably ugly. I remember discussing this with someone (hrs?) when this style of documenting advisories was first adopted, but at the time I was getting too burned out to care much (and neither of us had any good answers). Maybe we need to start thinking about this again.

We’re also thinking about some possible errata issues (non-security-related) to be fixed on RELENG_6_1 before handing it off. In some cases we’re waiting for the bugfixes to have proven themselves on HEAD and RELENG_6 first. I might try to at least write some of these items up for the errata document first, even if we don’t have fixes committed yet.