Snapcraft metadata links

snapcraft
1

Abstract

Generic system for associating links to snaps defined in a snapcraft.yaml to be exposed in snap.yaml.

Rationale

We would like to be able to have a way to manage links for snaps. Every time a link is added a new field is created. This field might not be used by all snaps, making this space consuming.
We would like to think of a new way to manage links related to a snap.

Specification

Available Fields

With these definitions:

  • link: scheme http[s]
  • email: optional mailto: prefixed address

This is the list of fields approved, each field should have the ability of supporting multiple entries:

  • Website: link to the website for the project/publisher
  • Contact: links/emails to contact the maintainer of the snap
  • Donation: links to a donation service that the maintainer uses
  • Source code: link to the source code of the published snap
  • Issues: link to issue tracker of the project

Snapcraft

The snapcraft.yaml must add the possibility to add some new top level fields that will be extracted by the store from a generated snap.yaml. Each field should be a list of links. Snapcraft must deal with a scalar value and transform it into a list of links for snap.yaml. Those top level fields are:

  • website
  • contact
  • donation
  • source-code
  • issues

In a snapcraft.yaml snippet this would be described as:

website: https://snapcraft.io
source-code: https://github.com/snapcore/snapcraft.
contact:
  - https://forum.snapcraft.io
  - snapcraft@forum.snapcraft.io
donations: https://donate.me
issues: https://bugs.launchpad.net/snapcraft/+filebug

Snap

Currently snapd retrieves the contact field over the Snap Store API. No contact field or similar is considered in and from snap.yaml.

The data in the snap is a source of information for the Snap Store and for Snapcraft’s upload-metadata.

Snapd would treat these entries generically with only general rules about keys and values, unless it has a specific use for a field. For backward consistency like the store it would use the first value of the contact list for its own already defined “contact” API field.

The snap.yaml from the already exposed snapcraft.yaml would look like:

links:
  website:
  - https://snapcraft.io
  source-code:
  - https://github.com/snapcore/snapcraft.git
  contact:
  - https://forum.snapcraft.io
  - snapcraft@forum.snapcraft.io
  donations:
  - https://donate.me
  issues:
  - https://bugs.launchpad.net/snapcraft/+filebug

Code changes

Schema

Snapcraft’s json schema would need to accept oneOf a single string or an array of string for each link.

Meta

Snapcraft’s Snap class in the meta package would need to be able to marshal and unmarshal this data correctly with the constraints on origin and destination being in either case snapcraft.yaml or snap.yaml.

Further Information

Out of scope:

  • Snapcraft’s upload-metadata as it requires Snap Store APIs to be available first.

As for the integration, this feature will only be production ready once:

  • Snap Store consumes the written data
  • review-tools are updated to allow for the extra data
  • store fronts (web, app) display the metadata
3

What’s the state of overall support here? I added such links as documented on https://snapcraft.io/docs/snapcraft-yaml-reference to my snapcarft.yml, but now the build got into manual review with a warning:

unknown entries in snap.yaml: ‘links’ lint-snap-v2_unknown_field

Is this expected?

4

@phw I don’t have knowledge of snapcraft’s status on this, but I am just beginning the work of adding this feature to the snap store’s backend servers, and presumably clients like snapcraft are waiting on that to be completed first. So it’ll be a little while yet.

1 Like
5

Snapcraft landed this 6 months ago as did snapd; the remaining outliers are review-tools (as it is not supported by Snap Store yet) and the Snap Store.

1 Like
6

Thanks for the info!

7

I tried it again, review seems to allow those links now. Snap store does not seem to use them yet, so that’s probably missing still.