On Nov 12, 2009, at 4:50, Graham Cobb wrote: > 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.
This is what the changelog was designed for. The control file should not be for messages but rather more like a compiled file that just happens to be text, users should not be reading it. According to debian policy source package control files only have five _mandatory_ fields. This means it is very unlikely that any X-* random header we invent will be used upstream or even downstream, and we are encouraging non-standard control files which may make Mer do non-standard stuff etc. We want compatibility across projects, therefor compatibility of control files across projects. I.e. a package built on Mempis should 'just work' on Maemo, Ubuntu, etc. Bunches of header files in the control file pollutes that namespace and makes compatibility harder, let's use the changelog. > 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. They are documentation. Documentation for the builders of the software. > Just as the header file is not suitable user documentation, > changelogs are not suitable upgrade documentation. I don't agree actually. > 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. Well if HAM has a little slug saying "Changed frobulation on foo: fixes security hole." that can come from the changelog just as well as the control file, perhaps more easily. > > 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. I actually think this method has some potential. Jeremiah _______________________________________________ maemo-developers mailing list maemo-developers@maemo.org https://lists.maemo.org/mailman/listinfo/maemo-developers
