Monday, June 20, 2011

Release logs are important!

Turns out that not many Free Software maintainers follow the practice of writing proper release logs targetted for packagers/end-users. To justify their laziness, they come-up with lame excuses like "Oh, the user never sees the release log" etc and at the very most copy&paste the (developer oriented) VCS changelog since the last release. Here is how it actually affects a user:


Now if you click on the URL provided, you will be taken to a page where there is a lot of information but the one you are looking for: What exactly changed? In this particular case, its just an bugfix release but many times new features are added and users can't know that unless you put that nicely in your release log.

So please stop justifying your laziness and take the efforts to write the release log if you are a maintainer of a Free Software project. OTOH, if you are a downstream packager, please copy or link to the upstream release log in your package's changelog that upstream maintainer has put his/her time/efforts into. Thanks!

9 comments:

Blue Lightning said...

Agreed. This is a huge personal annoyance of mine and I strongly encourage developers to write meaningful changelogs, written from an end-user impact perspective. It doesn't take long and users really appreciate it.

As a developer I try to do this for any software I'm in charge of releasing.

Anonymous said...

Release log? Not sure what you mean. Do you mean change logs or release notes?

Josh Triplett said...

I think that since ChangeLog files have become obsolete in favor of VCS commit logs, people sometimes forget that NEWS files still have a purpose.

Anonymous said...

+1

Manish said...

If the commit messages are proper in your version control system, then creating a technical release notes is not a big deal. If your bug tracker has the feature of targeting bugs to a milestone, then it become pretty easy to do so.

The biggest issue which you pointed out is that most of them still forget that non-technical release notes is important. I don't know much about inner working of git, but surely want to know about which bugs have been fixed and what new features are added. I might not need all the new features, but probably once in a while, one or two features might become useful

Jeremy Bicha said...

Debian & Ubuntu do a decent job with their changelogs in their packages. I agree it would be nice if Fedora would more consistently do the same since the update description is very visible in Fedora.

Leif said...

I always browse through the release logs provided by PackageKit with excitement. They also give me an idea of the severity of changes to expect. Sometimes I choose not to update a package.

It bothers me when I see packages with no notes! C'mon! If you don't take the time to tell the user what changed why should they take the time to update their software?

FelipeC said...

I call bullshit on this.

First of all, the example you provide (Git), is actually a counter-example.

The Git project doesn't have any NEWS file. It does in fact have release notes, but as you can see from the link, those are actually ignored by the Fedora packagers.

It seems the actual text is provided manually by the packager in the "update information".

zeenix said...

Felipe,

1. If you don't follow the usual convention (NEWS file), there is a very good possibility that people assume the information doesn't exist and hence "ignore" it.

2. I did not only stressed the maintainer to provide the release notes but also the packager to use it when it *is* provided.

3. I wrote this blog entry after talking to a guy who does a lot of packaging for fedora and he not only agrees but complained that he is sick&tired of stressing this to upstream maintainers and getting ignored.