Updates lacking descriptions

[Kevin Kofler]

Tom Lane wrote:
> Is a link to upstream's release notes sufficient?  If not, why not?

If the upstream release notes are reasonably complete and written in a style 
the target userbase of the package will understand (i.e. it's OK for MySQL 
to talk about a "transaction rollback", but if e.g. Amarok used that kind of 
vocabulary in their release notes, I'd stay perplexed to say the least ;-) 
I'm mainly writing this to make sure nobody will misunderstand me as 
suggesting to link to incomprehensible FSF-style function-level ChangeLog 
files, those are not release notes!), sure!

That said, one thing to keep in mind: if the previous stable version was, 
say, 1.2.3, then upstream released 1.2.4 and 1.2.5, and then you push out 
1.2.6 as an update, you'll also have to link to the release notes for 1.2.4 
and 1.2.5 for the user to be informed about all the changes.

> (For the packages I deal with, the upstream notes frequently run to
> several pages.  I see little point in extracting one or two sentences
> which is what the bodhi update notes seem to expect.)

Of course a link is OK in that case. It's like that for all the huge 
packages. (For example, there's no way we can summarize all the changes in 
KDE 4.3 in the Bodhi notes.) Thankfully, those tend to come with release 
notes ready to be linked to. The advice about writing down one or two 
sentences is intended for those many small packages whose maintainers often 
leave the notes blank or fill in just "new version".

(That said, if there's one change in particular which makes the update worth 
pushing, it can't hurt to explicitly mention it. But if it's mainly the 
aggregation of bugfixes which makes it worthwhile, then of course a link to 
upstream's list of fixes is sufficient.)

        Kevin Kofler