@vchernin
Copy link

vchernin commented Jan 1, 2022

Following examples here, I'm trying to write yaml release notes that can be converted to appstream metainfo.

Ideally I'd like paragraphs with bullet points roughly like:

Added
    - Cool new feature x
    - Cool new feature y

Bug fixes
    - Fixed bug a
    - Fixed bug b

However yaml-to-news and news-to-yaml --format=yaml doesn't seem to be able to preserve paragraphs with bullet points.

Demo of bug:
If you run metainfo-to-news --format=yaml on a metainfo file, then run news-to-metainfo --format=yaml on the same file the pargraph formatting is no longer preserved, the final metainfo release description is different from the original.

Working metainfo

From https://github.com/bottlesdevs/Bottles/blob/master/data/com.usebottles.bottles.appdata.xml.in

<?xml version="1.0" encoding="UTF-8"?>
<component type="desktop">
    <id>com.usebottles.bottles.desktop</id>
    <metadata_license>CC0-1.0</metadata_license>
    <project_license>GPL-3.0-or-later</project_license>
    <name>Bottles</name>
    <summary>Run Windows software</summary>
    <developer_name translatable="no">Mirko Brombin</developer_name>
    <description>
        <p>Run Windows software on Linux with Bottles!</p>
        <p>Bottle software and enjoy at your leisure!</p>
        <p>Our built-in dependency installation system grants automatic software
            compatibility access. Use the download manager to download the official components:
            the runner (Wine, Proton), DXVK, dependencies, etc.</p>
        <p>Bottle versioning keeps your work safe now and lets you restore it later!</p>
        <p>Features:</p>
        <ul>
          <li>Create bottles using preconfigured environments or create your own</li>
          <li>Run executables (.exe/.msi) in your bottles, directly from the context menu of your file-manager</li>
          <li>Automated detection of applications installed in your bottles</li>
          <li>Add environment variables quickly</li>
          <li>Override DLLs directly from per-bottle preferences</li>
          <li>On-the-fly runner change for any Bottle</li>
          <li>Various gaming-performance optimizations (esync, fsync, DXVK, cache, shader compiler, offload … and much more.)</li>
          <li>Automatic installation and management of Wine and Proton runners</li>
          <li>Automatic bottle repair in case of breakage</li>
          <li>Integrated dependency-installer based on a community-driven repository</li>
          <li>Integrated Task manager for Wine processes</li>
          <li>Access to ProtonDB and WineHQ for support</li>
          <li>System for bringing your configuration to new versions of Bottles</li>
          <li>Back up and import bottles</li>
          <li>Import Wine prefixes from other managers</li>
          <li>Bottles versioning (experimental)</li>
          <li>... and much more that you can find by installing Bottles!</li>
        </ul>
    </description>
    ​<mimetypes>
        <mimetype>application/x-ms-dos-executable</mimetype>
        <mimetype>application/x-msi</mimetype>
        <mimetype>application/x-ms-shortcut</mimetype>
        <mimetype>application/x-wine-extension-msp</mimetype>
    </mimetypes>
    <screenshots>
        <screenshot type="default">
            <image>https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/screenshot.png</image>
        </screenshot>
        <screenshot>
            <image>https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/1.png</image>
        </screenshot>
        <screenshot>
            <image>https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/2.png</image>
        </screenshot>
        <screenshot>
            <image>https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/3.png</image>
        </screenshot>
        <screenshot>
            <image>https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/4.png</image>
        </screenshot>
        <screenshot>
            <image>https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/5.png</image>
        </screenshot>
        <screenshot>
            <image>https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/6.png</image>
        </screenshot>
        <screenshot>
            <image>https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/7.png</image>
        </screenshot>
    </screenshots>
    <translation type="gettext">com.usebottles.bottles</translation>
    <content_rating type="oars-1.1"/>
    <url type="homepage">https://usebottles.com</url>
    <url type="bugtracker">https://github.com/bottlesdevs/Bottles/issues</url>
    <url type="help">https://docs.usebottles.com</url>
    <url type="donation">https://usebottles.com/funding</url>
    <url type="translate">https://hosted.weblate.org/engage/bottles</url>
    <recommends>
      <control>pointing</control>
      <control>keyboard</control>
      <control>touch</control>
    </recommends>
    <requires>
      <display_length compare="ge">768</display_length>
    </requires>
    <releases>
        <release version="2021.12.28-treviso" date="2021-12-27">
          <description>
            <p>News</p>
            <ul>
                <li>Bottles runtime updated to 0.2</li>
                <li>Caffe is now the new default runner, falling back to Vaniglia if not available</li>
                <li>New environment variables management, has also a nice new UI</li>
                <li>The new Operation manager handle tasks queue to avoid conflicts</li>
                <li>Improved xwayland support for runners when running in a wayland session</li>
                <li>Improved compatibility for optimus laptops</li>
                <li>Prevented value changes in preferences when scrolling on combo boxes</li>
                <li>Now the Crash Report dialog disable the send button if the report is already sent multiple times</li>
                <li>The new copy_file action can be used to copy any file during dependency installation</li>
                <li>Now is possible to rename manually added programs</li>
                <li>The uninstaller can now remove more than one program in one go (used by dependencies/installers)</li>
                <li>Improved DLSS support, now is automatically configured</li>
                <li>Extended the programs search to new directories</li>
            </ul>

            <p>Bug fixes</p>
            <ul>
                <li>Fixed onboard (first start-up) freeze on components download</li>
                <li>Fixed random crashes caused by non-safe thread access</li>
                <li>Fixed wayland support, was setting the wrong port for xwayland, the new method tests a bunch of ports to find the right one</li>
                <li>Fixed vkd3d installation, was failing due to a regression in command handling</li>
                <li>Fixed a crash during bottle creation caused by a non handled exception</li>
                <li>Fixed random crash saving environment variables</li>
                <li>Fixed a crash caused by the logger trying to split a None</li>
                <li>Fixed silent EasyTerm crash when gamemode is enabled but it doesn't find the executable</li>
                <li>Fixed wrong environment variables setting on non optimus laptops</li>
                <li>Fixed a crash caused by a non handled exception of Patool library</li>
                <li>Fixed Windows version change for winxp, was setting the wrong value for 64bit bottles</li>
                <li>Fixed a bug during initial checks</li>
            </ul>

            <p>Translations</p>
            <ul>
                <li>Chinese (Traditional) translations thanks to @XiaoPanPanKevinPan</li>
                <li>Italian translations thanks to @AlexzanDev, @phaerrax</li>
                <li>Czech translations thanks to @SoongVilda</li>
                <li>Russian translations thanks to @ZSHFan</li>
                <li>Finnish translations thanks to Jiri Grönroos</li>
                <li>French translations thanks to @GoudronViande24, @Bloombug, @julroy67</li>
                <li>Korean translations thanks to @OctopusET, @qogusdn1017</li>
                <li>Portuguese (Brazil) translations thanks to @redvulps, @davipatricio</li>
                <li>Vietnamese translations thanks to AD, Giai Ngo</li>
                <li>Portuguese translations thanks to @Bloombug</li>
                <li>Polish translations thanks to Krzysztof Marcinek</li>
                <li>Hindi translations thanks to @athenasaurav</li>
                <li>Spanish translations thanks to Alberto Cañaveras</li>
                <li>Indonesian translations thanks to neko</li>
                <li>German translations thanks to @McLutzifer, @Translator5</li>
                <li>Japanese translations thanks to @Hebi-no-Sekigae</li>
            </ul>
          </description>
        </release>
    </releases>
</component>

Then run:

appstreamcli metainfo-to-news --format=yaml com.usebottles.bottles.appdata.xml.in yaml_release_notes

Now converted to yaml release notes
---
Version: 2021.12.28-treviso
Date: 2021-12-27
Description: |-
  News
   * Bottles runtime updated to 0.2
   * Caffe is now the new default runner, falling back to Vaniglia if not available
   * New environment variables management, has also a nice new UI
   * The new Operation manager handle tasks queue to avoid conflicts
   * Improved xwayland support for runners when running in a wayland session
   * Improved compatibility for optimus laptops
   * Prevented value changes in preferences when scrolling on combo boxes
   * Now the Crash Report dialog disable the send button if the report is already sent multiple
     times
   * The new copy_file action can be used to copy any file during dependency installation
   * Now is possible to rename manually added programs
   * The uninstaller can now remove more than one program in one go (used by
     dependencies/installers)
   * Improved DLSS support, now is automatically configured
   * Extended the programs search to new directories

  Bug fixes
   * Fixed onboard (first start-up) freeze on components download
   * Fixed random crashes caused by non-safe thread access
   * Fixed wayland support, was setting the wrong port for xwayland, the new method tests a bunch of
     ports to find the right one
   * Fixed vkd3d installation, was failing due to a regression in command handling
   * Fixed a crash during bottle creation caused by a non handled exception
   * Fixed random crash saving environment variables
   * Fixed a crash caused by the logger trying to split a None
   * Fixed silent EasyTerm crash when gamemode is enabled but it doesn't find the executable
   * Fixed wrong environment variables setting on non optimus laptops
   * Fixed a crash caused by a non handled exception of Patool library
   * Fixed Windows version change for winxp, was setting the wrong value for 64bit bottles
   * Fixed a bug during initial checks

  Translations
   * Chinese (Traditional) translations thanks to @XiaoPanPanKevinPan
   * Italian translations thanks to @AlexzanDev, @phaerrax
   * Czech translations thanks to @SoongVilda
   * Russian translations thanks to @ZSHFan
   * Finnish translations thanks to Jiri Grönroos
   * French translations thanks to @GoudronViande24, @Bloombug, @julroy67
   * Korean translations thanks to @OctopusET, @qogusdn1017
   * Portuguese (Brazil) translations thanks to @redvulps, @davipatricio
   * Vietnamese translations thanks to AD, Giai Ngo
   * Portuguese translations thanks to @Bloombug
   * Polish translations thanks to Krzysztof Marcinek
   * Hindi translations thanks to @athenasaurav
   * Spanish translations thanks to Alberto Cañaveras
   * Indonesian translations thanks to neko
   * German translations thanks to @McLutzifer, @Translator5
   * Japanese translations thanks to @Hebi-no-Sekigae

Then run:

appstreamcli news-to-metainfo --format=yaml yaml_release_notes new-incorrect-metainfo

Now converted back to metainfo
<?xml version="1.0" encoding="utf-8"?>
<component type="desktop-application">
  <id>com.usebottles.bottles.desktop</id>
  <name>Bottles</name>
  <summary>Run Windows software</summary>
  <metadata_license>CC0-1.0</metadata_license>
  <project_license>GPL-3.0-or-later</project_license>
  <developer_name>Mirko Brombin</developer_name>
  <description>
    <p>Run Windows software on Linux with Bottles!</p>
    <p>Bottle software and enjoy at your leisure!</p>
    <p>Our built-in dependency installation system grants automatic software
            compatibility access. Use the download manager to download the official components:
            the runner (Wine, Proton), DXVK, dependencies, etc.</p>
    <p>Bottle versioning keeps your work safe now and lets you restore it later!</p>
    <p>Features:</p>
    <ul>
      <li>Create bottles using preconfigured environments or create your own</li>
      <li>Run executables (.exe/.msi) in your bottles, directly from the context menu of your file-manager</li>
      <li>Automated detection of applications installed in your bottles</li>
      <li>Add environment variables quickly</li>
      <li>Override DLLs directly from per-bottle preferences</li>
      <li>On-the-fly runner change for any Bottle</li>
      <li>Various gaming-performance optimizations (esync, fsync, DXVK, cache, shader compiler, offload … and much more.)</li>
      <li>Automatic installation and management of Wine and Proton runners</li>
      <li>Automatic bottle repair in case of breakage</li>
      <li>Integrated dependency-installer based on a community-driven repository</li>
      <li>Integrated Task manager for Wine processes</li>
      <li>Access to ProtonDB and WineHQ for support</li>
      <li>System for bringing your configuration to new versions of Bottles</li>
      <li>Back up and import bottles</li>
      <li>Import Wine prefixes from other managers</li>
      <li>Bottles versioning (experimental)</li>
      <li>... and much more that you can find by installing Bottles!</li>
    </ul>
  </description>
  <requires>
    <display_length>768</display_length>
  </requires>
  <recommends>
    <control>pointing</control>
    <control>keyboard</control>
    <control>touch</control>
  </recommends>
  <url type="homepage">https://usebottles.com</url>
  <url type="bugtracker">https://github.com/bottlesdevs/Bottles/issues</url>
  <url type="help">https://docs.usebottles.com</url>
  <url type="donation">https://usebottles.com/funding</url>
  <url type="translate">https://hosted.weblate.org/engage/bottles</url>
  <provides>
    <mediatype>application/x-ms-dos-executable</mediatype>
    <mediatype>application/x-msi</mediatype>
    <mediatype>application/x-ms-shortcut</mediatype>
    <mediatype>application/x-wine-extension-msp</mediatype>
  </provides>
  <translation type="gettext">com.usebottles.bottles</translation>
  <screenshots>
    <screenshot type="default">
      <image type="source">https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/screenshot.png</image>
    </screenshot>
    <screenshot>
      <image type="source">https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/1.png</image>
    </screenshot>
    <screenshot>
      <image type="source">https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/2.png</image>
    </screenshot>
    <screenshot>
      <image type="source">https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/3.png</image>
    </screenshot>
    <screenshot>
      <image type="source">https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/4.png</image>
    </screenshot>
    <screenshot>
      <image type="source">https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/5.png</image>
    </screenshot>
    <screenshot>
      <image type="source">https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/6.png</image>
    </screenshot>
    <screenshot>
      <image type="source">https://raw.githubusercontent.com/bottlesdevs/Bottles/master/data/appstream/7.png</image>
    </screenshot>
  </screenshots>
  <releases>
    <release type="stable" version="2021.12.28-treviso" date="2021-12-27T00:00:00Z">
      <description>
        <p>News
 * Bottles runtime updated to 0.2
 * Caffe is now the new default runner, falling back to Vaniglia if not available
 * New environment variables management, has also a nice new UI
 * The new Operation manager handle tasks queue to avoid conflicts
 * Improved xwayland support for runners when running in a wayland session
 * Improved compatibility for optimus laptops
 * Prevented value changes in preferences when scrolling on combo boxes
 * Now the Crash Report dialog disable the send button if the report is already sent multiple
   times
 * The new copy_file action can be used to copy any file during dependency installation
 * Now is possible to rename manually added programs
 * The uninstaller can now remove more than one program in one go (used by
   dependencies/installers)
 * Improved DLSS support, now is automatically configured
 * Extended the programs search to new directories</p>
        <p>Bug fixes
 * Fixed onboard (first start-up) freeze on components download
 * Fixed random crashes caused by non-safe thread access
 * Fixed wayland support, was setting the wrong port for xwayland, the new method tests a bunch of
   ports to find the right one
 * Fixed vkd3d installation, was failing due to a regression in command handling
 * Fixed a crash during bottle creation caused by a non handled exception
 * Fixed random crash saving environment variables
 * Fixed a crash caused by the logger trying to split a None
 * Fixed silent EasyTerm crash when gamemode is enabled but it doesn't find the executable
 * Fixed wrong environment variables setting on non optimus laptops
 * Fixed a crash caused by a non handled exception of Patool library
 * Fixed Windows version change for winxp, was setting the wrong value for 64bit bottles
 * Fixed a bug during initial checks</p>
        <p>Translations
 * Chinese (Traditional) translations thanks to @XiaoPanPanKevinPan
 * Italian translations thanks to @AlexzanDev, @phaerrax
 * Czech translations thanks to @SoongVilda
 * Russian translations thanks to @ZSHFan
 * Finnish translations thanks to Jiri Grönroos
 * French translations thanks to @GoudronViande24, @Bloombug, @julroy67
 * Korean translations thanks to @OctopusET, @qogusdn1017
 * Portuguese (Brazil) translations thanks to @redvulps, @davipatricio
 * Vietnamese translations thanks to AD, Giai Ngo
 * Portuguese translations thanks to @Bloombug
 * Polish translations thanks to Krzysztof Marcinek
 * Hindi translations thanks to @athenasaurav
 * Spanish translations thanks to Alberto Cañaveras
 * Indonesian translations thanks to neko
 * German translations thanks to @McLutzifer, @Translator5
 * Japanese translations thanks to @Hebi-no-Sekigae</p>
      </description>
    </release>
  </releases>
  <content_rating type="oars-1.1"/>
</component>

Notice how different the <releases> section is.

The issue isn't necessarily about that one can't convert metainfo perfectly back and forth. Rather, that there doesn't seem to be a way to define paragraphs with bullet points in the yaml release notes format. yaml-to-news --format=yaml not preserving the paragraphs is (presumbably) a reflection of that.

From what I can tell in the blog post's example, a news file instead of yaml should not experience this bug.

Note technically apptreamcli validate complains about the example metainfo (along with all the others I tried), but the warnings don't seem relevant.