[maemo-developers] Now *that*'s what I call a changelog...

[From: Quim Gil]

Hi,

On Fri, 2007-08-10 at 13:45 +0100, ext Andrew Flegg wrote:
> On 8/10/07, Daniel Stone <daniel.stone at nokia.com> wrote:
> > On Fri, Aug 10, 2007 at 01:25:45PM +0100, ext Andrew Flegg wrote:
> > > With all the recent discussion about release notes and changelogs,
> > > *this* is what I like to see in a changelog:
> > >
> > >     http://browser.garage.maemo.org/news/4/

Yes, the browser team have set a good precedent with the release notes
of their last update. Needless to say they followed the discussion about
changelogs here, so you have helped setting these standards.

As an exercise, let me check this release notes against the factors I
mentioned in my previous email on the changelog debate:

NEW FEATURES vs FIXED BUGS
This is all about bugfixes. The developers got directly all the bugs
submitted in the public bugzilla and worked on them. Good.

END USER ORIENTED vs DEVELOPER ORIENTED
The browser itself is oriented to end users and this is why it gets so
much attention. However we are still in development mode and this is why
this specific release could get into technical details. Note that the
same release notes would not be ready for pure tablet users.

INTERNAL vs EXTERNAL
The browser version under development was released to get external
feedback in addition to the internal testing. I don't know if the
browser team has detailed bugfixes found only internally. It's their
choice. They clearly are reporting the fixes of public bugs. Good.

DISTRIBUTION vs PACKAGES
The release notes affect just one application and just one or a small
set of packages. They can concentrate in all these details. Good.

OPEN SOURCE vs PROPRIETARY
It's an open source component and the release notes are done in the
typical open source way. Good.

NOKIA DEVELOPED vs THIRD PARTY
Developed by Nokia, we had most control (and responsibility) over the
bugfixes and therefore over the release notes. I don't know whether any
fix in the Mozilla engine development upstream had an influence in this
update. Good.

If you look at this profile you will see that there are not many other
applications matching the same criteria. The RTCom update under
development and the Modest client would be the most comparable
examples. 

> >
> > Except for the categorisation (and HTML format, instead of text), what
> > you then want is essentially /usr/share/doc/*/changelog.Debian.gz.
> 
> Effectively, yes. Although I find the categorisation helpful, this
> doesn't need to be done after the fact.
> 
> As had already been pointed out, there are pages which list the
> variation in packages; assuming they have good changelogs, from a
> Maemo point of view it should be possible to auto-generate a decent
> changelog.
> 
> I'd try to do it this afternoon, but would need some more information:

Good that you want to help. Last week we started discussing the
possibility to extract changelog and news files contents from all the
packages and include this information as part of the release notes.


>   * What's the difference between the Content Comparison Table[1] and the
>     Content Changes Table[2]?

Those links refer to maemo. We are near to publish a content comparison
table for the whole Internet Tablet OS 2007. We've got the table and now
we are polishing some presentation details.

http://tablets-dev.nokia.com/3.2/content_comparison.html lists all the
maemo packages even if there are no changes across releases.
http://tablets-dev.nokia.com/3.2/content_changes.html lists only
packages with changes.


>   * Are these sorts of tables going to be released for future updates? (I'm
>     not writing a tool for a one-off)

Yes, both the maemo and the IT OS tables.


>   * For this release, are there finally no differences between the packages
>     in the IT OS and the corresponding SDK? If not, are their equivalent
>     tables for the packages which make up an IT OS release?

The IT OS table to be published includes all the non-free packages that
are not present in the SDK.

>   * What's the definitive place to get the source for a given package?

Mmm... not sure what you mean by "definitive" but this is what we have
now: http://repository.maemo.org/pool/maemo3.2/free/source/

>   * Where's the equivalent for the open IT OS packages which aren't part of
>     Maemo[3], such as osso-rss-feed-reader?

The IT OS content comparison table should answer this question.


> Having a quick look at some of the random entries, however shows that
> not all the debian/changelog entries have the same level of thought
> that timeless has put in, for example from libconic:

Checking again the factors mentioned above we see that the Mozilla based
browser and the libconic package have very different profiles. Expecting
the same "level of thought" is probably not realistic. However, if
libconic is not providing the most essential information about changelog
and news relevant to the developers using this component (as it happens
now) then this is not good - agreed.

Even if this has nothing to do with end users it is indeed a problem of
quality. Increasing internally the awareness of these changelogs and
news and announcing that we will publish them as part of the release
noted for Chinook and onwards should help.

>   * Fixed freeing of a GError. Fixes: NB#49308.
> 
> Admittedly, if that bug was accessible the description of it could
> also be pulled out into the complete changelog. Unfortunately, even
> the open source components of an IT OS release are closed
> developments, but this is a long rant for another day (which I don't
> think we're ever going to get solved satisfactorily).

Focusing first in certain profiles of components should help. Raising
good examples of not good practices should help too. 

Thanks for nailing so good.

-- 
Quim Gil - http://maemo.org