Device data format specification

The devices shown on this website are added from markdown and yaml files stored at the website repository in the data/devices folder. Each device has its own folder named by the codename the manufacturer has assigned to the device.

The device folder has a main file called data.md that contains all the data that does not change between software releases. Data on the device type and specifications will be placed in this file.

In the same folder is located the releases directory that contains a markdown file for each version of Ubuntu Touch available. These files are named after the adjective of the Ubuntu release on which the release is based, for example xenial.md or focal.md.

We will then have a structure similar to the following:

suzu
├── data.md
└── releases
    ├── focal.md
    └── xenial.md

Adding new devices

You can add new devices by creating a Markdown file with a YAML metadata block under data/devices/<codename>/data.md and a Markdown file for each release available under data/devices/<codename>/releases/<release>.md. The YAML metadata block is a snippet of YAML in your otherwise Markdown-formatted document, and is denoted by three dashes alone on the line above and below the block.

---
name: My Ported Device
deviceType: phone
...
---

<section id="notes">

## You should know...

This device occasionally requests an offering of bacon. Don't ask, just provide.

</section>

<section id="preinstall">

## Preinstallation instructions

Before using the UBports Installer on this device, ...

</section>

There are complete templates of device markdown files for devices and releases downloadable from the website. Copy that document and fill in your device’s information as needed. Note that some optional sections which are listed in the YAML metadata block reference are not included in the example document. Carefully review the available information and fill in as much as you can.

Device file

Your YAML metadata block will have four primary sections. For more information on filling these sections, see the YAML metadata block reference below.

Device description

name: "My Cool Device"
deviceType: "phone"
description: "My Cool Device features an absurd 100:1 screen ratio that ensures you never have to scroll a webpage."
buyLink: "https://example.com"

The root level of the YAML contains base information about the device, such as its name and type.

The subforum

subforum: <the subforum id on forums.ubports.com, should be added in the format number/my-device>

The subforum is a category in the UBports forum to discuss your device port with users and developers. If you would like a forum category for your device, make a post in the forum’s General section.

The subforum id is necessary to display forum posts in the sidebar. To add it search for the subforum on the Ubports forum. The url should look like this “https://forums.ubports.com/category/number/my-awesome-device”. Take only the last two parameters in the url bar that should be in the format “number/my-awesome-device”.

Device variants

variantOf: "main-device-codename"

In case your device has many codenames or you are grouping devices of the same port you can use the variantOf keyword to inherit properties of another device by its codename.

Device specifications

deviceInfo:
  - id: "chipset"
    value: "Qualcomm MSM8956 Snapdragon 650"

The deviceInfo section contains an overview of the device’s specifications. The following data should be filled in:

Contributors

contributors:
  - name: Yumi
    photo: <link to avatar picture>
    forum: <link to ubports forum profile>
    role: <Phone maker|Maintainer|Developer|Tester|Contributor>
    renewals:
        - <Maintainership renewal date in format YYYY-MM-DD (maintainers only)>

This is a place to credit the people who have worked on this device port. List them by name and their UBports Forum profile link. If they have a profile picture set on the forum, copy the image link for that picture and add it as the photo key. Otherwise, a 3D render of the Yumi mascot for UBports will be used instead.

The devices website also keeps track of device maintenance. Devices running Ubuntu Touch need to be updated from time to time on a device-specific basis in order to enable new features or complete porting progress. In addition, during system updates following the completion of porting, it is possible that some changes may cause a device's functionality to regress. Therefore, and in order to apply security patches at the hardware level, we need someone who is willing to perform these functions for an extended period of time.

If you would like to become a maintainer of your device, you can register by setting the role to maintainer and writing today's date for the first renewal. Each renewal lasts for 6 months, before the end of which you can renew the maintainer role by writing a new date in the renewals in a merge request. In case you can no longer fulfil the role of maintainer you can always open a merge request to inform us and set the property expired: true.

If the phone manufacturer supports Ubuntu Touch on the device, the "Phone maker" role can be added, which for the purposes of maintaining the device is equivalent to the maintainer but does not require periodic renewals. When the manufacturer decides to stop providing updates, they can inform us by setting the expired: true property.

Sources and bug tracking

sources:
  portType: "community"
  portPath: "android9"
  deviceGroup: "volla-phone"
  deviceSource: "volla-yggdrasilx"
  kernelSource: "kernel-volla-mt6763"
  issuesLink: "https://github.com/HelloVolla/ubuntu-touch-beta-tests/issues"

In order to list your device on the website, you must publish the sources. Devices will be grouped into three categories based on where the sources are published:

• Reference devices: devices that the core developers have and are developing and testing Ubuntu Touch on are listed here
• Community devices: devices developed by the community and accepted in the Ubports' Gitlab repositories
• External devices: devices with sources hosted on public repositories owned by the developer

When listing a reference device or a community device you will need to set the portPath to the device group starting from the reference or community ports group on Gitlab and the id of the group in the deviceGroup property. Then set the deviceSource and kernelSource links to the correct IDs of the repositories in the device group. The issuesLink is not required for reference and community ports, it is required only for external ports, it needs to be set to an URL where people can report problems they’re having with your port. On reference and community devices, the issuesLink is the issues URL of the device source repository, if it needs to be changed it can be overwritten with the issuesRepo or issuesLink property.

External links, community help and doc links

externalLinks:
  - name: "Issue tracker"
    link: "https://gitlab.com/ubports/ubuntu-touch/-/issues"

External links help visitors find more information about your device port. This section will be added automatically if the sources of your device are available in the community or reference port repositories. If your device is located in an external repository you will need to add manually the links to the sources in this section. Reference and community ports can also use this section to add more details and useful links that are not already listed in the sources section. The link for issue reports is automatically added for all the ports from the sources and it shouldn't be added to the links.

For ports with external sources all relevant source repositories (device, device_common, kernel, manifest) should be linked if possible.

communityHelp:
  - name: "Telegram - @utonvolla"
    link: "https://t.me/utonvolla"

Community help links help visitors to get help with using the device. This is the place to add device specific groups to help users and developers with installation and testing. DO NOT add the device subforum, the main UBports group or the WelcomePlus group, they will be added automatically.

Doc links are links to UBports docs and blog posts that mention the device or might be useful to the user.

Releases file

You’ll need to add a release file to display a working release on the devices website. This file contains the feature matrix and information about the porting type.

Feature IDs

portStatus:
  - categoryName: "Sound"
    - id: "earphones"
      value: "-"
      bugTracker: "https://link to my bug report"

The portStatus matrix allows the site to display the hardware compatibility of your port. This helps users discover ports that meet their needs and sets expectations for people looking to buy a device for Ubuntu Touch.

If your device has hardware support for a given feature and it can be used under Ubuntu Touch, set the value: key to "+". This marks the feature as working.

If your device does not have hardware support for a given feature, set the value: key to "x". The site will ignore any missing features when calculating the progress value for your device.

If your device has hardware support for a feature but it does not work when running Ubuntu Touch, set the value: key to "-". This marks the feature as broken.

Mark a feature as partially working if your device has hardware support for the feature and it works most of the time when running Ubuntu Touch, but most users will encounter a critical issue with the feature within 1 week of booting the device. The value: key for partially working features is "+-"

If you haven’t tested a feature or you don’t know its state you can set the value: key to "?".

If possible, include a bug report link with the bugTracker key when marking a feature as broken or partially working.

The markdown block

---

<section id="preinstall">

- This is the Markdown list
- Before using the UBports Installer on this device, ...

</section>

<section id="notes">

## This is the Markdown block

I can write Markdown content here. Have [a link](https://example.com)!

</section>

The markdown block of your file will be displayed in different places on the page of your device. Four sections can be added.

The preinstall section should contain instructions for steps required before using the UBports installer to flash the device. For example, if your device needs to have a certain version of Android installed before running the UBports Installer. This section overrides the instructions fetched from the installer configuration file, if any.

The manual-install section provides installation instructions if the installer for the port is not yet available. In this case, it is recommended that the port maintainer host the installation instructions themselves, and link to them in the installLink property. Manual installation is not supported by the community. This section is maintained for backwards compatibility.

The credits section allows you to add links to indirect contributors and projects from which your work is derived.

The notes section allows the porter to add additional content to the page, such as port status and instructions for using the device.

Do not place a description or a marketing blurb in the markdown block. It will look out of place. Use the description key in the YAML metadata block instead.

YAML metadata block reference

The YAML metadata block for data.md should have the following format:

name: "<retail name of the device>"
description: "<marketing-style description that helps a user decide if this device is right for them>"
subforum: "<the subforum id on forums.ubports.com, should be added in the format number/my-device>"
deviceType: "<phone|tablet|laptop|tv|other>"
tag: "<promoted|unmaintained>"
buyLink: "<link to manufacturer's store, if it is available>"
disableBuyLink: "<true|false>"
image: "<link to a picture of the device (currently unused)>"
price:
  min: "<minimum estimated price>"
  max: "<maximum estimated price>"
  currency: "<currency in the ISO 4217 format USD|EUR>"
  currencySymbol: "<currency symbol $|€>"
variantOf: "<device codename to inherit config from>"
deviceInfo:
  - id: "<device specification ID, you can find the complete list above>"
    value: "<device technical specification, model...>"
contributors:
  - name: "<contributor name>"
    role: "<Phone maker|Maintainer|Developer|Tester|Contributor>"
    renewals:
      - "<date of maintainership renewal (add a new one every 6 months)>"
    expired: "<mark as true if maintainership ended before the 6 months of renewal>"
    forum: "<link to ubports forum profile>"
    photo: "<link to avatar picture>"
communityHelp:
  - name: "<link label>"
    link: "<URL for the user to get help during installation and usage>"
docLinks:
  - name: "<link label>"
    link: "<URL to UBports docs or blog posts>"
sources:
  portType: "<reference|community|external>"
  portPath: "<path to the device group or repository>"
  deviceGroup: "<device group name>"
  deviceSource: "<device source repository name>"
  kernelSource: "<kernel source repository name>"
  issuesRepo: "<repository for issues tracking when it isn't the device repository>"
  showDevicePipelines: "<add pipelines URL to device resources true|false>"
  issuesLink: "<link to open an issue (for external ports or when is not the device repository)>"
externalLinks:
  - name: "<link label>"
    link: "<URL for development resources>"
    noActivityDetection: "<Disable activity checking, if it is a link to Github or Gitlab>"
unimplementedFeatures:
  - name: "<Name of the feature not supported by the OS that the device has>"
seo:
  description: "<Page description, used as content in <meta name='description' content=''>>"
  keywords: "<Comma-separated list of keywords, used as content in <meta name='keywords' content=''>>"

The YAML metadata block for release.md should have the following format:

portType: "<Legacy|Native|Halium 5.1|Halium 7.1|Halium 9.0|Halium 10.0|Halium 11.0|Halium 12.0>"
kernelVersion: "<version of the Linux kernel running in the format x.y.z>"
installLink: "<link to install instructions (repo), if installer isn't available>"
portStatus:
  - categoryName: "<name of the category of the features>"
    features:
      - id: "<feature ID, you can find the complete list above>"
        value: "< + | - | +- | x | ? >"
        bugTracker: "<link to the relevant issue report if this feature is not working>"
maturity: "<fallback value for progress calculation, MUST NOT be used>"