[maemo-developers] QA process = bug fixing disincentive?

[From: Graham Cobb]

On Wed, Nov 11, 2009 at 04:29:55PM +0200, Marius Vollmer wrote:
> ext Thomas Perl <th.perl at gmail.com> writes:
> 
> > The following is a rant about XB-Maemo-Upgrade-Description
> > with some suggestions for improvement...
> 
> Yeah, as soon as I 'invented' it, I could see how it is not going to
> work very well.  I actually think it is best to ignore this field.

Actually, I disagree.  I don't see this field as being anything like a
changelog.  It is an alternative description to display to someone who
already has the program installed and hence, probably, already knows what it
does any why they should install it but does not know whether they should
bother to install this particular release.

So, for a security update it would contain text something like:

This is an important security update that should be installed as soon as
possible.

For beta-testing releases (releases that will never be promoted beyond
extras-testing) I do use it to describe the user-visible changes since the
last full release, including bug numbers fo fixed bugs.  However, for real
releases (which will get promoted into Extras) I use it to give a general
view of the release.  For example, for a (fictional) 2.7.4 release, the text might
read:

This update contains many bug fixes since version 2.7, particularly in
import and export capabilities. The only change since 2.7.3 is a fix to
Edit menu handling in portrait mode.

> 
> > My suggestion is to either use the Debian changelog, or if this sounds
> > too "technical" for the end user, agree on some way to mark
> > "user-relevant" changes in the Debian changelog (by using "USER:" as a
> > prefix for a one-line summary or by having a convention of having the
> > first entry in the Debian changelog be a user-friendly summary of all
> > changes) and then parse the changelog and display all user-relevant
> > changes in the AppMgr.
> 
> Yes, we pretty much have to have a full list of changes and the
> Application manager then can display the relevant ones.  The
> apt-listchanges program does this for Debian.

But the audiences are completely different.  changelog's are not
documentation.  Just as the header file is not suitable user documentation,
changelogs are not suitable upgrade documentation.  The user description has
to answer the question "why should I install this", the changelog has to
answer the question "what has changed" -- the answers are related but are
not the same and cannot be generated form the same source.  Particularly as
the descriptions have to be read in a specific layout in the AppMgr, which
is much better suited to a paragraph of natural language text than a
detailed list.  And don't forget the requirements of translation as well.

Keep the upgrade description.  If some people want to generate it
automatically from their changelogs that is fine -- I can imagine an
mh-generateupdatedescfromchangelog program which can be called from
debian/rules.  But don't do it automatically.

Graham