| ngraham | |
| ltoscano |
| Gwenview |
Copy the release notes as worked on for the kde.org announcements to
the AppStream metadata, so they show up in software centers like Discover
once distributions ship a version of Gwenview containing this change in
their repositories.
Closes T8426
Check validity with appstreamcli validate app/org.kde.gwenview.appdata.xml.
Try it in action in Discover: Install to /usr and set PreferLocalMetainfoData=true in /etc/appstream.conf.
| No Linters Available |
| No Unit Test Coverage |
As discussed in T8426, this is headed for master. Will wait for the final release notes next week and possibly update the patch.
Patch only for Gwenview for now, to be able to test the process.
@ngraham Couple of issues to note for Discover Software Store (and no, I'm not motivated to file bugs with detailed steps to reproduce currently, sorry…):
As mentioned in the task, I'm not sure that this the way to go. It's even more relevant because this may set a precedent and going back could be complicated.
Just to add more details:
Fine for release dates, maybe, but ... I'd rather find a different solution.
Thanks @rkflx!
If desired, we can consider this a test of the process. Hopefully @apol can chime in, as someone very familiar with AppStream, software centers, the KDE release process, and translation.
@ltoscano
From a user perspective, it's highly desirable to be able to display these kinds of release notes right there in the software center. Even if it's abridged, with a link to a KDE website or something, that's still hugely better than nothing. This is one of things that AppStream was created to enable. I agree that we should come up with a technical process that makes this painless though.
Thanks, that's all really helpful. No bugs necessary, I'll go fix 'em...
xdg-open appstream://org.kde.gwenview.desktop
The exact URI may depend on your distro though, sadly... Could be org.kde.gwenview or gwenview.desktop. You can check with appstreamcli search gwenview
@ltoscano Would you be fine with the length of the notes for the minor releases (if you run the patch, you can simply comment out the rest)? Also see how it's done here: https://github.com/hexchat/hexchat/blob/master/data/misc/io.github.Hexchat.appdata.xml.in
(I now set you as blocking reviewer, to make sure this won't go in without your consent.)
Anyway, I'm not married to the approach, at least we got the ball rolling…
So put a link to the release notes on the website.
Even if something is enabled, it does not always mean that it's the best solution to use. The appstream tag is for release *information*, not release notes.
I can mention at least another solution for release notes which I find better (https://docs.openstack.org/reno/latest/) but it's not something that can be decided by one project alone.
Sorry, I don't understand - what do you mean by "run the patch"? Which rest?
I understand how it's done and I don't see it scaling. But that's maybe me.
I was trying with what you see via plasma-discover -h, but turns out this is probably a distro issue (worked fine with another distro) or maybe the way I installed from source. Don't worry about it if it is working fine for you.
I see a quite a few apps using this feature for release notes, and the Flathub people certainly seem to think that per-release notes are appropriate. See https://github.com/flathub/flathub/issues/273
But why don't we ask @mak? He created all of this, after all. Rather than guessing what the intention was, we can just find out once and for all.
Follow the test plan, i.e. get a feel for what users see in Discover, instead of only looking at the XML. Having a link to some release notes is not really helpful, and on other platforms displaying inline release notes is standard.
Which rest?
Comment out the 18.04 notes, so Discover shows the 17.12.3 release notes. Those don't take so much vertical space ;)
I understand how it's done and I don't see it scaling. But that's maybe me.
Good point. Maybe my idea about providing online access to the notes similar to how it's done for the screenshots is then the way to go.
The bug is about "Applications missing release information" and my point is the same: it's for a short description, it can't replace the full release notes. And even if could, it would not scale. Bigger projects do not put all the release notes in a single file (unless it's generated dynamically, which is another possibility).
But why don't we ask @mak? He created all of this, after all. Rather than guessing what the intention was, we can just find out once and for all.
Sure: I did it in the task that spawned this discussion.
Which other platforms?
Android application show a brief summary of the changes.
F-droid provides (if the application defines it) a link to the proper changelog.
Which rest?
Comment out the 18.04 notes, so Discover shows the 17.12.3 release notes. Those don't take so much vertical space ;)
It's not about how they are shown; it's about how they are stored and the way the file should be edited and merged. I'm not talking about the visualization part. If you want the release notes inline, there are other ways than letting developers edit this file.
Sure, I think everyone is fine with a process that populates the file with this data automatically. In fact, that would be ideal.
Sorry, I should have been more specific. Yes, one of the platforms I had in mind was Android. Cannot check which apps I meant right now ("no updates" currently), but those would display a long list of detailed changes, not just some links or a short blurb. You had access to all details, but could also easily dismiss (might have been K9-Mail and/or OsmAnd).
It's not about how they are shown; it's about how they are stored and the way the file should be edited and merged. I'm not talking about the visualization part. If you want the release notes inline, there are other ways than letting developers edit this file.
I know, I was only answering your question about "which rest". Let's get back to working on a solution ;)
Just checked: gnome-software does not display release notes currently (not sure if simply missing or intentionally). I'd guess there is some kind of bug, because normally at least the Release Activity icon will light up once there is a <release>.
As already mentioned, flathub.org does display the release notes already.
Talking about "the tool provide something, but it may not be the best idea": the more we discuss the more I found absurd to link the release date information in the appstream file: while we have a good process, releases can slip for whatever reason and adding the information ahead of the timesounds just backward; you will always run after the releases to update them.
This is probably on Google Play, not on F-Droid. But that's not connected on the way those information are stored. That's my entire concern.
(If my memory is right, anyway, both applications shows the detailed changes during the first start after an update, but that's unrelated).
It's not about how they are shown; it's about how they are stored and the way the file should be edited and merged. I'm not talking about the visualization part. If you want the release notes inline, there are other ways than letting developers edit this file.
I know, I was only answering your question about "which rest". Let's get back to working on a solution ;)
The solution depends also on the agreement that pushing the details to this XML file is the right thing to do, and when this should be done (merging the information during tarball creation, or stored somewhere else, or manually changed by the developer).
What if we provided the <release> tag XML on the website, instead of embedding in the tarball? Discover could then just pull it down live and display them the same way it does currently.
If I understand it correctly, that would result in the same good UX like this patch, which also avoiding the issues with having developers embed the release notes in the tarball.
Conceptually, that might be the way to go.
Discover could then just pull it down live and display them the same way it does currently.
Sounds simple, but this will need some preparation:
To make this great, even more steps are necessary:
In any case, we need release information on software centers.
Maybe there's somewhere better to put the data, but in the end it boils down to having it somewhere together with the tarball.
I'm a bit afraid that just putting it on the appstream file could make it go stale. It needs to be part of the release process. But that's a matter of scripting and thoroughly announcing releases.
Sure, but the question is: Which information does this entail? Only the release date? A single line of description? Something like in KDE's announcements? A detailed changelog? More structured data? Unless we know what software centers want to show, it is hard for apps to provide exactly the information that is needed.
Maybe there's somewhere better to put the data, but in the end it boils down to having it somewhere together with the tarball.
How do you propose to solve the translation deadline issue then?
I'm a bit afraid that just putting it on the appstream file could make it go stale.
@ltoscano Here is an idea to improve scalability (but not yet solve translations): Have a release-notes.xml in the repo which will grow forever but is not shipped in distro packages, and on tagging day extract the last couple of release tags (number or time-based) and put them in the appstream XML.
It needs to be part of the release process. But that's a matter of scripting and thoroughly announcing releases.
Do we want scripted information or allow for manual polishing? Not every "Fix typo" commit should be shown IMO, and it should allow for manual additions…
The intent of the "short summary" wording in the AppStream spec for release descriptions is that people don't start to list every single commit that went into the release there, but give a user-friendly translatable overview there instead.
Future releases of AppStream will contain some tooling to add release entries from easier to write formats (Markdown files, YAML, ...), but doing that will not work with KDEs translation process (it would involve translating the XML metainfo file at build-time, while at the moment translations are injected directly into the file by the KDE l10n script - so, to use that KDE would need to use xgettext at build time in combination with e.g. Weblate).
I am in general not yet very happy with the way the release information works in AppStream, chances are that we will add the option to decouple it from the metainfo file in future and treat it like we treat the screenshots tag: Have people reference some URL in the metainfo file from where to get the release information. This will allow translating the release texts post-release and editing them as needed. Distributors would cache the release information just like they cache screenshots at time.
That's all future ideas at the moment though.