This article isn t about anything new , like the previous ones on AppStream it rather exists to shine the spotlight on a feature I feel is underutilized. From conversations it appears that the reason simply is that people don t know that it exists, and of course that s a pretty bad reason not to make your life easier
Mini-Disclaimer: I ll be talking about appstreamcli, part of AppStream, in this blogpost exclusively. The appstream-util tool from the appstream-glib project has a similar functionality check out its help text and look for appdata-to-news if you are interested in using it instead.
What is this about?
AppStream permits software to add
release information to their MetaInfo files to describe current and upcoming releases. This feature has the following advantages:
- Distribution-agnostic format for release descriptions
- Provides versioning information for bundling systems (Flatpak, AppImage, )
- Release texts are short and end-user-centric, not technical as the ones provided by distributors usually are
- Release texts are fully translatable using the normal localization workflow for MetaInfo files
- Releases can link artifacts (built binaries, source code, ) and have additional machine-readable metadata e.g. one can tag a release as a development release
The disadvantage of all this, is that humans have to maintain the release information. Also, people need to write XML for this. Of course, once humans are involved with any technology, things get a lot more complicated. That doesn t mean we can t make things easier for people to use though.
Did you know that you don t actually have to edit the XML in order to update your release information? To make creating and maintaining release information as easy as possible, the
appstreamcli utility has a few helpers built in. And the best thing is that
appstreamcli, being part of AppStream, is available pretty ubiquitously on Linux distributions.
Update release information from NEWS data
The
NEWS file is a
not very well defined textfile that lists user-visible changes worth mentioning per each version. This maps pretty well to what AppStream release information should contain, so let s generate that from a NEWS file!
Since the news format is not defined, but we need to parse this somehow, the amount of things
appstreamcli can parse is very limited. We support a format in this style:
Version 0.2.0
~~~~~~~~~~~~~~
Released: 2020-03-14
Notes:
* Important thing 1
* Important thing 2
Features:
* New/changed feature 1
* New/changed feature 2 (Author Name)
* ...
Bugfixes:
* Bugfix 1
* Bugfix 2
* ...
Version 0.1.0
~~~~~~~~~~~~~~
Released: 2020-01-10
Features:
* ...
When parsing a file like this,
appstreamcli will allow a lot of errors/ imperfections and account for quite a few style and string variations. You will need to check whether this format works for you. You can see it in use in
appstream itself and
libxmlb for a slightly different style.
So, how do you convert this? We first create our NEWS file, e.g. with this content:
Version 0.2.0
~~~~~~~~~~~~~~
Released: 2020-03-14
Bugfixes:
* The CPU no longer overheats when you hold down spacebar
Version 0.1.0
~~~~~~~~~~~~~~
Released: 2020-01-10
Features:
* Now plays a "zap" sound on every character input
For the MetaInfo file, we of course generate one using the
MetaInfo Creator. Then we can run the following command to get a preview of the generated file:
appstreamcli news-to-metainfo ./NEWS ./org.example.myapp.metainfo.xml - Note the single dash at the end this is the explicit way of telling
appstreamcli to print something to stdout. This is how the result looks like:
<?xml version="1.0" encoding="utf-8"?>
<component type="desktop-application">
[...]
<releases>
<release type="stable" version="0.2.0" date="2020-03-14T00:00:00Z">
<description>
<p>This release fixes the following bug:</p>
<ul>
<li>The CPU no longer overheats when you hold down spacebar</li>
</ul>
</description>
</release>
<release type="stable" version="0.1.0" date="2020-01-10T00:00:00Z">
<description>
<p>This release adds the following features:</p>
<ul>
<li>Now plays a "zap" sound on every character input</li>
</ul>
</description>
</release>
</releases>
</component>
Neat! If we want to save this to a file instead, we just exchange the dash with a filename. And maybe we don t want to add all releases of the past decade to the final XML? No problem too, just pass the
--limit flag as well:
appstreamcli news-to-metainfo --limit=6 ./NEWS ./org.example.myapp.metainfo.tmpl.xml ./result/org.example.myapp.metainfo.xml
That s nice on its own, but we really don t want to do this by hand The best way to ensure the MetaInfo file is updated, is to simply run this command at build time to generate the final MetaInfo file. For the
Meson build system you can achieve this with a code snippet like below (but for
CMake this shouldn t be an issue either you could even make a nice macro for it there):
ascli_exe = find_program('appstreamcli')
metainfo_with_relinfo = custom_target('gen-metainfo-rel',
input : ['./NEWS', 'org.example.myapp.metainfo.xml'],
output : ['org.example.myapp.metainfo.xml'],
command : [ascli_exe, 'news-to-metainfo', '--limit=6', '@INPUT0@', '@INPUT1@', '@OUTPUT@']
)
In order to also translate releases, you will need to add this to your .pot file generation workflow, so (x)gettext can run on the MetaInfo file with translations merged in.
Release information from YAML files
Since parsing a no structure, somewhat human-readable file is hard without baking an AI into
appstreamcli, there is also a second option available: Generate the XML from a YAML file. YAML is easy to write for humans, but can also be parsed by machines.The YAML structure used here is specific to AppStream, but somewhat maps to the NEWS file contents as well as MetaInfo file data. That makes it more versatile, but in order to use it, you will need to opt into using YAML for writing news entries. If that s okay for you to consider, read on!
A YAML release file has this structure:
---
Version: 0.2.0
Date: 2020-03-14
Type: development
Description:
- The CPU no longer overheats when you hold down spacebar
- Fixed bugs ABC and DEF
---
Version: 0.1.0
Date: 2020-01-10
Description: -
This is our first release!
Now plays a "zap" sound on every character input
As you can see, the release date has to be an
ISO 8601 string, just like it is assumed for NEWS files. Unlike in NEWS files, releases can be defined as either
stable or
development depending on whether they are a stable or development release, by specifying a
Type field. If no
Type field is present,
stable is implicitly assumed. Each release has a description, which can either be a free-form multi-paragraph text, or a list of entries.
Converting the YAML example from above is as easy as using the exact same command that was used before for plain NEWS files:
appstreamcli news-to-metainfo --limit=6 ./NEWS.yml ./org.example.myapp.metainfo.tmpl.xml ./result/org.example.myapp.metainfo.xml If
appstreamcli fails to autodetect the format, you can help it by specifying it explicitly via the
--format=yaml flag. This command would produce the following result:
<?xml version="1.0" encoding="utf-8"?>
<component type="console-application">
[...]
<releases>
<release type="development" version="0.2.0" date="2020-03-14T00:00:00Z">
<description>
<ul>
<li>The CPU no longer overheats when you hold down spacebar</li>
<li>Fixed bugs ABC and DEF</li>
</ul>
</description>
</release>
<release type="stable" version="0.1.0" date="2020-01-10T00:00:00Z">
<description>
<p>This is our first release!</p>
<p>Now plays a "zap" sound on every character input</p>
</description>
</release>
</releases>
</component>
Note that the
0.2.0 release is now marked as
development release, a thing which was not possible in the plain text NEWS file before.
Going the other way
Maybe you like writing XML, or have some other tool that generates the MetaInfo XML, or you have received your release information from some other source and want to convert it into text. AppStream also has a tool for that! Using
appstreamcli metainfo-to-news <metainfo-file> <news-file> you can convert a MetaInfo file that has release entries into a text representation. If you don t want
appstreamcli to autodetect the right format, you can specify it via the
--format=<text yaml> switch.
Future considerations
The release handling is still not something I am entirely happy with. For example, the release information has to be written and translated at release time of the application. For some projects, this workflow isn t practical. That s why
issue #240 exists in AppStream which basically requests an option to have release notes split out to a separate, remote location (and also translations, but that s unlikely to happen). Having remote release information is something that will highly likely happen in some way, but implementing this will be a quite disruptive, if not breaking change. That is why I am holding this change back for the AppStream 1.0 release.
In the meanwhile, besides improving the XML form of release information, I also hope to support a few more
NEWS text styles if they can be autodetected. The
format of the systemd project may be a good candidate. The YAML release-notes format variant will also receive a few enhancements, e.g. for specifying a release URL. For all of these things, I very much welcome pull requests or issue reports. I can implement and maintain the things I use myself best, so if I don t use something or don t know about a feature many people want I won t suddenly implement it or start to add features at random because they may be useful . That would be a recipe for disaster. This is why for these features in particular contributions from people who are using them in their own projects or want their new usecase represented are very welcome.
Here is my monthly update covering what I have been doing in the free software world during March 2020 (
Update a few hours later: an update came in, version 1.7.62, which fixed this misbehavior!!!!
I have been using the 
From time to time, we get questions in Debian about our official channels of
communication and questions about the Debian status of who may own similarly
named websites.
The main Debian website 
Welcome to gambaru.de. Here is my monthly report (+ the first week in March) that covers what I have been doing for Debian. If you re interested in Java, Games and LTS topics, this might be interesting for you.
Debian Games
The day has finally arrived: 
This year s 
) or make something up, which occasionally is wrong and not the actual component-ID their software component should have.
The MetaInfo Creator
It was actually suggested to me twice that what people really would like to have is a simple tool to put together a MetaInfo file for their software. Basically a simple form with a few questions which produces the final file. I always considered this a nice to have, but not essential feature, but now I was convinced that this actually has a priority attached to it.
So, instead of jumping into my favourite editor and writing a bunch of C code to create this make MetaInfo file form as part of 
Wouter s tasks
Wouter s props, needed to complete his tasks
Bike tour leg at Cape Town Stadium.
Seeking out 29 year olds.
Wouter finishing his lemon and actually seemingly enjoying it.
Reciting South African national anthem notes and lyrics.
The national anthem, as performed by Wouter (I was actually impressed by how good his pitch was).
Accommodation at the lodge
Debian swirls everywhere
I took a canoe ride on the river and look what I found, a paddatrapper!
A bit of digital zoomage of previous image.
Time to say the vows.
Just married. Thanks to Sue Fuller-Good for the photo.
Except for one character being out of place, this was a perfect fairy tale wedding, but I pointed Wouter to 
Here is my monthly update covering what I have been doing in the free software world during February 2020 (
sbuild is a tool used by those maintaining packages in Debian, and
derived distributions such as Ubuntu. When used correctly, it can
catch a lot of categories of bugs before packages are uploaded. It
does this by building the package in a clean environment, and then
running the package through the Lintian, piuparts, adequate and
autopkgtest tools. However, configuring sbuild so that it makes use
of all of these tools is cumbersome.
In response to this complexity, I wrote 
I've been tempted to run own 
The server runs Debian sid (probably it would be doable on stretch as well, but I didn't try much) and the setup was pretty simple.
First we need to install some things - Bitcoin daemon and ElectrumX dependencies:
Previously: 