Every Metainfo file should describe the releases the software has made. Release descriptions are shown to users in software centers, they tell bundling systems like Flatpak which versions exist, they are translatable like the rest of the metadata, and they can carry machine-readable information such as resolved security issues or download artifacts.

The downside is that all of this has to be written as XML, in addition to the release notes a project usually keeps anyway. To avoid maintaining the same information twice, appstreamcli can generate the releases block of a metainfo file from a project's release notes, and can also go the other way and produce release notes from an existing metainfo file.

This document describes those two commands and the two file formats they accept. It does not describe the resulting XML itself - see Section 2.2, “Release Information” for the specification of the releases tag.

Two input formats are supported for conversion into Release/Metainfo XML:

A YAML release-notes file is a stream of YAML documents, one per release, separated by ---. Releases are written newest first. A typical file, conventionally named NEWS.yaml, looks like this:

---
Version: "1.2.0"
Date: 2024-05-14
Type: development
URL: https://example.com/myapp/releases/1.2.0
Description:
- Added a *dark mode* setting
- The CPU no longer overheats when you hold down the spacebar
- Fixed the rendering of `--verbose` output
Resolved:
- name: bug#1234
  url: https://example.com/bugs/1234
- cve: CVE-2026-0001

---
Version: "1.1.0"
Date: 2024-01-10
Description: |-
  This release is all about the new rendering engine.

  The engine was rewritten from scratch:
   * it is now roughly twice as fast
   * it finally supports fractional scaling, which
     a lot of you have been asking for

  Everything else is unchanged.

The root of every document must be a mapping. A document without a Version key is skipped, and keys that are not listed below are ignored, so you can keep additional data in the file for your own tooling.

5.4.2.2 Writing the description #

A description is written either as a YAML list or as a block of free-form text.

A list is the simplest form and becomes a single enumeration. This description:

Description:
- Added a *dark mode* setting
- The CPU no longer overheats when you hold down the spacebar

results in this markup:

<description>
  <ul>
    <li>Added a <em>dark mode</em> setting</li>
    <li>The CPU no longer overheats when you hold down the spacebar</li>
  </ul>
</description>

Free-form text is written as a YAML block scalar and may mix paragraphs and enumerations. Paragraphs are separated by blank lines. A line that starts with a space followed by * or - is an enumeration entry, and a longer entry can be wrapped by indenting the continuation line so that it lines up with the text of the entry. A line written as a Markdown heading, such as ### Under the hood, becomes a section <heading/>; a line that merely ends in a colon stays a paragraph, as in the example below.

Description: |-
  This release is all about the new rendering engine.

  The engine was rewritten from scratch:
   * it is now roughly twice as fast
   * it finally supports fractional scaling, which
     a lot of you have been asking for

  Everything else is unchanged.

This results in:

<description>
  <p>This release is all about the new rendering engine.</p>
  <p>The engine was rewritten from scratch:</p>
  <ul>
    <li>it is now roughly twice as fast</li>
    <li>it finally supports fractional scaling, which a lot of you have been asking for</li>
  </ul>
  <p>Everything else is unchanged.</p>
</description>

Note

The indentation shown above is what the block scalar looks like in the file. YAML strips the common indentation of a block scalar before the text is converted, so the bullets end up with exactly one leading space and their continuation lines with three, which is what the converter expects. If you indent your file differently, keep the bullets one space further in than the surrounding paragraphs, and their continuation lines aligned with the entry text.

Many projects already keep a NEWS file listing the user-visible changes of each release. appstreamcli can read a common subset of the styles found in the wild:

Version 1.2.0
-------------
Released: 2024-05-14

This release is all about the new rendering engine.

Features:
 * Added a *dark mode* setting
 * The renderer now supports fractional scaling, which
   a lot of you have been asking for

Bugfixes:
 * The CPU no longer overheats when you hold down the spacebar
 * Fixed the rendering of `--verbose` output, see [#1234](https://example.com/bugs/1234)

Under the hood:
 * The renderer no longer keeps a global state

Resolved Issues:
 * CVE-2026-0001

Version 1.1.0
-------------
Released: 2024-01-10

Features:
 * Now plays a "zap" sound on every character input

A new release starts with a header block: a line beginning with Version, a space and the version number, followed by an underline of at least four ~, - or = characters. The header must contain a Released: line with a date in YYYY-MM-DD form; conversion fails if it is missing. Anything before the first version header is ignored, so a title or preamble at the top of the file does no harm.

The rest of a release is made up of blocks separated by blank lines. A block that starts with one of the recognized headings is converted accordingly; the headings are Bugfix:, Bugfixes:, Bug fixes:, Features:, Removed features:, Notes:, Note:, Misc:, Miscellaneous:, Documentation:, Specification:, Resolved Issues:, Resolved:, Translations:, Translation:, Contributors:, With contributions from:, Thanks to: and Translators:. They are matched case-sensitively, and may equally be written as a Markdown heading such as ### Features, in which case the colon can be left out.

A block header that is none of these names is recognized as a section heading of its own if it looks like one: it has to be a line by itself, it has to end with a colon, and it has to be followed either by an enumeration or by an empty line. Everything else stays prose - a paragraph that happens to end in a colon is not turned into a heading. A block without a recognized heading directly after the version header is turned into plain paragraphs, and any other unrecognized block is appended to the block before it, so no content is ever dropped.

Within a block, lines starting with a * or - bullet are enumeration entries, and a line indented by three spaces continues the entry above it. The header line itself becomes a <heading/> for everything that follows it, so the Features: block above becomes <heading>Features</heading> followed by the enumeration. Since a heading needs AppStream 1.2, see <description/> for how older implementations treat it.

Version 1.3.0
-------------
Released: 2024-08-xx

Features:
 * Still being worked on

<release type="development" version="1.3.0" date="2026-08-24T18:42:28Z">

AppStream descriptions permit only two inline tags, <em/> and <code/>. Both input formats therefore understand the small subset of Markdown that corresponds to them:

Everything else is written out as it is. In particular there is no “strong” markup in AppStream, so **bold** stays literal, and a delimiter is only treated as such when it directly touches the text it marks up: 2 * 3 * 4 and foo* bar are left alone, and an unmatched * or ` is kept as written. A span never continues past the end of a line, so an enumeration entry can never accidentally emphasize the entry after it.

Note

metainfo-to-news writes these markers back out again, so emphasis and code spans survive a conversion in either direction. The same holds for section headings, which are written as Heading: in a text NEWS file and as ### Heading in Markdown and YAML output.

Release entries can list the issues a release resolves, which is particularly useful for security fixes. See <issues/> for what the generated data looks like.

In a YAML file, issues are listed explicitly using the Resolved key described above. In a NEWS file, they are picked up from the text:

An issue is only recorded once even if it is mentioned several times, and links pointing at the CVE or GCVE databases are dropped, because such a link can be derived from the identifier anyway.

To see what your release notes will be converted into, pass - as the metainfo file. Only the resulting release entries are printed, which makes this a quick way to check the result:

$ appstreamcli news-to-metainfo ./NEWS.yml -

To produce a complete metainfo file, pass the metainfo file to insert the releases into. A metainfo file has to exist already - if you do not have one yet, create it as described in Section 5.1, “For GUI application upstream maintainers” or with the MetaInfo Creator (https://www.freedesktop.org/software/appstream/metainfocreator/#/). A third argument names the file to write to; - writes the complete metainfo XML to standard output.

$ appstreamcli news-to-metainfo ./NEWS.yml ./org.example.myapp.metainfo.xml -

If the third argument is omitted, the metainfo file is modified in place. Note that in either case the release entries generated from the release notes replace the releases already present in the metainfo file, rather than being added to them.

The input format is guessed from the file name: .yml and .yaml are read as YAML, .md as Markdown, and NEWS, news or .txt as text. Any other name is read as YAML. Use --format=yaml|text|markdown if that guess is wrong. The text and markdown formats are read identically and differ only when writing.

Two options control how much data ends up in the metainfo file:

5.4.6.1 Separate release metadata files #

Release information does not have to live inside the metainfo file. It can also be kept in a file of its own, with releases as its root element, which the metainfo file then points at with an empty <releases type="external"/> tag. This keeps a long release history out of the metainfo file and lets the release notes be updated on their own. See Section 2.2.2, “Locations” for where such a file has to be installed.

Both commands accept these files wherever they accept a metainfo file. Which kind of file they are dealing with is decided by its root element, so the name an existing file carries in your source tree does not matter.

Unlike a metainfo file, a release metadata file is also created if it does not exist yet, since it holds nothing besides the releases that are about to be written. A file that is not there has no root element to look at, so this works only for names ending in .releases.xml (or .releases.xml.in, for files that still have to be translated) - which is what the file has to be called anyway:

$ appstreamcli news-to-metainfo ./NEWS.yml ./org.example.myapp.releases.xml

The metainfo file itself then only carries the reference:

<component type="desktop-application">
  <id>org.example.myapp</id>
  ...
  <releases type="external"/>
</component>

Note

When a metainfo file uses external release data, running metainfo-to-news on it will not write an empty NEWS file, but tell you to run the command on the release metadata file instead.

ascli_exe = find_program('appstreamcli')

metainfo_with_relinfo = custom_target('gen-metainfo-rel',
    input : ['NEWS.yml', 'org.example.myapp.metainfo.xml'],
    output : ['org.example.myapp.metainfo.xml'],
    command : [ascli_exe, 'news-to-metainfo', '--limit=6', '--translatable-count=4',
               '@INPUT0@', '@INPUT1@', '@OUTPUT@']
)

If you maintain the release information in the metainfo file itself, or receive it from some other tool, the conversion can be reversed to produce release notes from it:

$ appstreamcli metainfo-to-news ./org.example.myapp.metainfo.xml ./NEWS.yaml

A separate release metadata file, as described in Section 5.4.6.1, “Separate release metadata files”, can be used as input in exactly the same way.

The output format is guessed from the file name using the same rules as above. Use --format=yaml|text|markdown to select it explicitly; the markdown format differs from text in the character used to underline the version headers, and in writing section headings as ### Heading instead of Heading:. Passing - as the output file writes to standard output, in which case --format is required.

Note

Converting to YAML and back is lossless, so a YAML file can be regenerated at any time. The text and Markdown formats keep section headings and enumerations as well, but they are a lossier target: a heading that already ends in a colon loses it, as a trailing colon is what marks a heading in a NEWS file, and an ordered list (<ol/>) is not read back as a list. Pick one of the representations as the place where you maintain your release notes, and generate the others from it.