How detailed should be <release> tags?

[Jehan]

Hi!

Someone proposes us (GIMP) to use the appdata <release> tags instead of NEWS (and actually even to generate NEWS from these <release> appdata).

As we start using <release>, this makes sense since that is a bit duplicate info, especially since now we can add a "type" to a release tag (cf. #158, thanks for this!).
Yet I wonder how detailed you expect the <release> data to be. Our NEWS file is pretty detailed (this can be considered as the most exhaustive human readable text for new features of a release; if you want more detailed basically you look at the git log): https://git.gnome.org/browse/gimp/tree/NEWS

I may be wrong, but I feel that you don't expect the <release> tags to be this detailed. Since this is used as release information in a software installer, I assumed you expect more a concise text only featuring the biggest changes.
For instance, here is the text I started to write for our 2.10 release: https://git.gnome.org/browse/gimp/tree/desktop/org.gimp.GIMP.appdata.xml.in.in#n73
As you can see, just a few major points (this is like 50 times smaller than even each intermediary release in NEWS).

Could you tell us what you think? Does it make sense to have extra-detailed <release> tags, in which case, we would merge the NEWS concept into appdata (NEWS may just become a generated file)? Or should the appdata just be a summarized and succinct version of NEWS, telling of a release in a few points?

[hughsie]

It's a style thing indeed. I would expect the release info to be readable (so less than say 4 paragraphs) and it should be designed for a non-technical user. The primary purpose is so the user can decide "do I want to do this update" and the secondary purpose IMHO is for marketing. I don't think it's terribly useful to see every change that happened, and this is a case where maybe the NEWS page and the appdata could diverge. In my head, if you want to know exactly what changed you can just use git, even in a browser so the need to list every commit in the release is somewhat outdated. All IMO, obviously.

[Jehan]

In my head, if you want to know exactly what changed you can just use git, even in a browser so the need to list every commit in the release is somewhat outdated.

We don't list every commit in NEWS (also we don't list bug fixes, neither minor structural changes, etc.), only features and major structural changes, but also public API (for plug-in developers). Note-worthy things for someone exterior to the project, in an exhaustive way, basically.
It's also summarized, but at a lower level than "marketing text". git log is still much huger. For a few dozens commits which add a given features, then fix things, etc., we'd get a single 2-line item in NEWS. It's actually very useful to keep track in a project with a big activity and find information of what was added in a release without going through dozens of commits one by one.

I would expect the release info to be readable (so less than say 4 paragraphs) and it should be designed for a non-technical user. The primary purpose is so the user can decide "do I want to do this update" and the secondary purpose IMHO is for marketing.

Anyway from your answer, I guess my assumptions on appdata expectations were right.

I actually also thought of some intermediary: development <release> tags would be extra-detailed like our current NEWS; stable <release> tags would be short and punchy (summarizing the whole intermediary dev releases in a few lines). That might be feasible since usually you are not supposed to change much between the last dev release and the stable one (though that could happen with our slightly chaotic organization).

Yet I think that wouldn't do either since the development <release> would also be visible if you install them; and even for dev releases, I don't think the expectations of a short punchy description in the installer would be that different. You may expect slightly more technical talk in a dev release, but still not 100+ lines of description (as we have in NEWS). I guess you agree?

If so, I will just tell the reporter that we can't merge the 2 concepts because they are still a bit too different.

[Jehan]

Ok thanks @hughsie. In the end, we won't merge NEWS and appdata. I am thinking that maybe this may happen in the future as we are trying to release new features more often. So we may end up with much smaller release notes which might make for acceptable listing size as both NEWS and appdata. But not now, I think.
Closing the question.

Reference: https://bugzilla.gnome.org/show_bug.cgi?id=779839