Changelog entries for post-release updates

Fri Feb 3 19:31:25 UTC 2012

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

- -----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

- - -----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Clint Byrum wrote on 01/02/12 04:32:
> ...
> 
> Excerpts from Scott Kitterman's message of Tue Jan 31 19:04:29 
> -0800 ...
>> 
>> ifupdown (0.7~alpha5.1ubuntu5.1) oneiric-proposed; urgency=low
>> 
>> * Cherry pick fixes for label handling from upstream git (LP: 
>> #876829): -
>> http://anonscm.debian.org/hg/collab-maint/ifupdown/rev/100d6f75b985
>>
>> 
- - http://anonscm.debian.org/hg/collab-maint/ifupdown/rev/2d171c8da8e5
>> -
>> http://anonscm.debian.org/hg/collab-maint/ifupdown/rev/f9cef973859e
>>
>> 
- - http://anonscm.debian.org/hg/collab-maint/ifupdown/rev/80a68bbbd45d
>> * Update test suite accordingly.
> ...
> 
> We, the SRU team, should have rejected this changelog, per point 4
>  on https://wiki.ubuntu.com/StableReleaseUpdates
> 
> "Upload the fixed package to release-proposed with the patch in
> the bug report, a detailed and user-readable changelog, and no
> other unrelated changes."
> 
> I have to agree with Scott that this was not user-readable, and 
> perhaps this point should be stressed a bit.

I'm not sure what you mean by "user-readable". If you mean
"understandable by a typical PC owner", then in my seven years using
Ubuntu I have not yet seen a changelog that is user-readable. So
merely stressing the point may not help, ;-) and maybe we should
discuss what would work instead.

Consider the DigiNotar key revocation last year. Here's what the
update changelog looked like in Windows:
|
| Update for Windows 7 (KB2616676)
|
| Install this update to resolve an issue which requires an update to
| the certificate revocation list on Windows systems and to keep your
| systems certificate list up to date. _Details..._

What was good about this? It was written in plain English, and it told
you that the update resolved the problem. What was bad about it? It
didn't actually tell you *what* the problem was, when you might
encounter it, or how dangerous it was. But it did link to a Knowledge
Base article that, in turn, linked to a detailed security bulletin
answering those questions. (If you're prepared to click on enough
links, Microsoft documents their updates up the wazoo.)

Here's how the update changelog appeared in OS X:
|
| Security Update 2011-005
|
| *   Certificate Trust Policy
|
|     Available for: Mac OS X v10.6.8, Mac OS X Server v10.6.8, OS X
|     Lion v10.7.1, Lion Server v10.7.1
|
|     Impact: An attacker with a privileged network position may
|     intercept user credentials or other sensitive information
|
|     Description: Fraudulent certificates were issued by multiple
|     certificate authorities operated by DigiNotar. This issue is
|     addressed by removing DigiNotar from the list of trusted root
|     certificates, from the list of Extended Validation (EV)
|     certificate authorities, and by configuring default system trust
|     settings so that DigiNotar's certificates, including those issued
|     by other authorities, are not trusted.

What was good about this? It was written in plain English. It
explained what the problem was, and how dangerous it was. It even
explained how the fix solved the problem. What was bad about it? Not
much, though it didn't tell you when you might have encountered the
problem (e.g. when visiting a Web site).

Now here's how the equivalent update (or one of them, at least)
appeared in Ubuntu:
|
|  * SECURITY UPDATE: Add patch from Debian version 3.12.11-3 rebased
| against
|    3.12.9 to remove the DigiNotar certificates and actively distrust
| them;
|    Thanks to Mike Hommey from Debian for the original patch (LP:
| #837557)
|    - mozilla/security/nss/lib/ckfw/builtins/certdata.*:
|      Explicitely distrust various DigiNotar CAs:
|      - DigiNotar Root CA
|      - DigiNotar Services 1024 CA
|      - DigiNotar Cyber CA
|      - DigiNotar Cyber CA 2nd
|      - DigiNotar PKIoverheid
|      - DigiNotar PKIoverheid G2
|    - mozilla/security/nss/lib/ckfw/builtins/certdata.*:
|      Remove DigiNotar Root CA.
| -- Micah Gersten <micahg at ubuntu.com> Wed, 07 Sep 2011 14:53:13 -0500

What was good about this? It named the developers responsible for the
update, a nice personal touch. What was bad about it? It didn't say
what the problem was, when you might have encountered it, or how
dangerous it was. It was riddled with jargon: "Debian", "rebased",
"nss/lib/ckfw", "certdata". It was written in imperative mood, which
could have been misinterpreted as instructions. ("I'm supposed to add
a patch from Debian version? how do I do that?") It didn't say whether
the update completely resolved the problem. And it misspelled
"Explicitly", making the update seem less trustworthy.

Now, I'm not at all picking on Micah here. This was a completely
typical Ubuntu changelog. Almost every Ubuntu changelog has roughly
the same problems.

How might we fix this?

At UDS Karmic in 2009, the Ubuntu Security Team discussed a new format
for Ubuntu Security Notices that would have made them much more
user-readable.
<https://wiki.ubuntu.com/SecurityTeam/Specifications/USNSpec> But
because the work was tracked as a Launchpad blueprint, when it didn't
get done that cycle, it disappeared into a black hole. Perhaps it
could be revived, and adapted for Ubuntu updates generally, not just USNs.

A complementary approach could be some kind of Mad-Libs-style software
for helping developers construct user-readable (and spell-checked)
changelogs. "This update {resolves a problem where} {an attacker
could} {...}." "This update {resolves a problem where} {name of
application} might {close unexpectedly} while {attempting a particular
task}." "This update {improves} {battery life} for {Lenovo Thinkpad
computers}." "This update {improves} {wi-fi signal} for {some
computers with Realtek wi-fi cards}." And so on.

- - --
mpt
- -----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk8sNYoACgkQ6PUxNfU6ecrj7QCeIdKxv6Ek+1utsHz+XcII1RUb
4sEAnjjMoCHGU28Msatg55v7KFW2vwCk
=9nXn
- -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk8sNgwACgkQ6PUxNfU6ecp2HwCfZx/4puWz/nMoWEiDlesmpbUx
w8wAnAtK28XEz6B9VKFcY49G0VNfBfhu
=9q7r
-----END PGP SIGNATURE-----