On Wed, Nov 11, 2009 at 04:29:55PM +0200, Marius Vollmer wrote: > ext Thomas Perl <th.p...@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 _______________________________________________ maemo-developers mailing list maemo-developers@maemo.org https://lists.maemo.org/mailman/listinfo/maemo-developers
