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.
A new small package with a new C++ header library is now on CRAN. It brings the date library by Howard Hinnant to R. This library has been in pretty wide-spread use for a while now, and adds to C++11/C++14/C++17 what will be (with minor modifications) the date library in C++20. I had been aware of it for a while, but not needed thanks to CCTZ library out of Google and our RcppCCTZ package. And like CCTZ, it builds upon std::chron adding a whole lot of functionality and useability enhancement. But a some upcoming (and quite exciting!) changes in nanotime required it, I had a reason to set about packaging it as RcppDate. And after a few days of gestation and review it is now available via CRAN.
Two simple example files are included and can be accessed by 
This is my last Outreachy blogpost, as my internship unfortunately has come to an end. It was a blast!
Through the 
I have profited so much from other people s work, so I am very happy if community members can build on mine. Afterall sharing is caring!
Through the Outreachy travel stipend I was able to 
I completed six email templates for the DebConf sponsor communication campaigns. While two of them have already been very useful, I hope my
other proposals will be the ones used for the next waves of sponsors contacting.
I committed them to the sponsors git repo so they can be easily accessible and well documented for other DebConf teams or can be recycled for
smaller Debian events.
Unfortunately, due to the insecurity about travel around the Corona virus pandemic, the third wave of communication, originally scheduled for
the end of my internship in March, has been held. I have committed to the team to do this once the travel restrictions have been lifted and we
know that DebConf20 can proceed as planned for August 2020.
So yeah, I am definitely going to stay around and continue to help with DebConf fundraising!
DebConf has been held for two decades and it also has a generic website, so I also updated the
I am trying to avoid bringing coronovirus into my house on anything,
and I also don't want to sterilize a lot of stuff. (Tedious and easy to
make a mistake.) Currently it seems that the best approach is to leave
stuff to sit undisturbed someplace safe for long enough for the virus to
degrade away.
Following that policy, I've quickly ended up with a porch full of stuff
in different stages of quarantine, and I am quickly losing track of how
long things have been in quarantine. If you have the same problem,
here is a solution:
I wanted to have a working Two Factor Authentification (2FA) setup to login on salsa.debian.org, Debians s gitlab instance.
The following contributors got their Debian Developer accounts in the last two months:
Hey folks,
This is a quick blog post to tell you Bandcamp is 
The fourth maintenance release 1.0.4 of 