Jump to content Jump to page navigation: previous page [access key p]/next page [access key n]
AppStream
AppStream › Metadata Quickstart › Maintaining release information
AppStream › Metadata Quickstart › Maintaining release information
Top
←→

## 5.4 Maintaining release information #

### 5.4.1 Introduction #

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, described in Section 5.4.2, “Release notes in YAML”. This format was designed for this purpose, it maps directly onto the AppStream release data and is parsed deterministically.

- A plain-text `NEWS` file, described in Section 5.4.3, “Release notes in a NEWS file”. Since the `NEWS` format is not standardized in any way, the converter applies a set of heuristics to it. Use this if you already maintain such a file and do not want to change it.

### 5.4.2 Release notes in YAML #

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.1 Recognized keys #

`Version`

  The version number of the release. This key is required.

  Always quote the value. Without quotes, YAML will read `1.2` as a floating-point number and a version like `1.20` would lose its trailing zero.

`Date`

  The release date, either as `YYYY-MM-DD` or as a complete ISO 8601 timestamp.

`Type`

  The kind of release: `stable`, `development` or `snapshot`. If this key is absent, `stable` is assumed.

`URL`

  A link to more detailed release notes for this release, for example an announcement blog post. It becomes the release's `details` URL. For compatibility, the spelling `Url` is accepted as well.

`Description`

  The user-visible description of the release, either as a list of entries or as free-form text. See Section 5.4.2.2, “Writing the description”. The key may also be spelled `Notes`.

`Resolved`

  A list of issues that this release resolves, each one a mapping. The key may also be spelled `Issues`. Recognized keys of an entry are:

  `name`

    The issue identifier, for example a bug number. `id` is accepted as an alias.

  `cve`

    A CVE identifier. Using this key sets the issue identifier and marks the issue as a CVE at the same time.

  `gcve`

    A GCVE identifier, handled like `cve`.

  `url`

    A link to the issue. This is not needed for CVE and GCVE entries, as a link into the respective vulnerability database is generated automatically.

  `type`

    The issue type, if it was not already implied by using the `cve` or `gcve` key.

#### 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.

### 5.4.3 Release notes in a NEWS file #

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.

#### 5.4.3.1 Marking a release as unreleased #

Unlike the YAML format, a `NEWS` file has no place to record the type of a release. There is however a convention for the release that is still being worked on: write the day of the date as `xx`, `XX` or `??`.

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

    Features:
     * Still being worked on

Such a release is marked as a development release and dated with the day the conversion is run:

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

Replacing the placeholder with the real day right before tagging then turns it into a regular stable release.

### 5.4.4 Markup in descriptions #

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

`*emphasis*`

  becomes `<em>emphasis</em>`.

``code``

  becomes `<code>code</code>`. The content of a code span is used literally, so an asterisk inside one does not start emphasis.

`\*`, `\``, `\\`

  produce a literal `*`, ``` or `\`.

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.

### 5.4.5 Referencing issues #

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:

- A Markdown link whose text looks like an issue reference - it starts with `#` or `issue#`, or is a CVE or GCVE identifier - is registered as an issue with that link. Since links are not valid in AppStream descriptions, only the link text remains in the description itself, so `[#1234](https://example.com/bugs/1234)` is rendered as `#1234`.

- CVE and GCVE identifiers mentioned anywhere in the text are registered as issues as well, and are kept in the description. Identifiers are recognized regardless of case and normalized to their canonical spelling.

- A `Resolved Issues:` block lists issues instead of description text. Its entries take the form `ID` or `ID: URL`. Entries that do not look like an issue reference are kept as ordinary enumeration entries so that nothing is lost.

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.

### 5.4.6 Generating the metainfo file #

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:

`--limit`

  Only convert the given number of releases, newest first. Without it, a project with a long history would carry its complete changelog in every installed metainfo file.

`--translatable-count`

  Only mark the descriptions of the given number of releases as translatable; the older ones are written with `translate="no"` and will not show up for translation. This keeps your translation template from growing without bound while still translating the releases people actually read.

#### 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.

#### 5.4.6.2 Integrating with Meson #

The conversion is best run as part of the build, so that the release notes remain the only place where release information is maintained:

    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@']
    )

The generated file is the one that should be installed, translated and validated. If you translate your metainfo file with Itstool as described in Section 5.5, “Translating Metadata”, use the output of this target as the input of the `itstool_join` step, and extract the translatable strings from it as well, so that the release descriptions are picked up.

### 5.4.7 Going the other way #

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.