About Store updating package metadata fields on every upload: the transition


We’re adding support in the Store server side and snapcraft to update the package metadata fields on every upload. This will improve the current situation where some fields are set on the first upload, but if you want to change them you need to go through the web, you can’t just change them in the YAML file.

After this feature is done, you will be able to change package metadata on every upload (and also through the web, of course, we’re not removing that). Also there is a security mechanism that will prevent doing changes via web and forgetting to update the content locally: on the next upload snapcraft will alert you that there are conflicts between local content and the one you modified through the web (detailing both sides). If you want to learn more about this whole interaction, see here.

The metadata fields we’re taking care in this first phase are:

  • summary (text)
  • description (text)
  • icon (binary)
  • screenshots (binary, support to be added in the YAML file)

As previous to this feature the only data set through an upload was for the first one (leading you to need to use the web for further changes), and after this feature it will set the metadata on every upload, we need to take care of the transition.

The cases where you never changed anything through the web, or what you changed via web you also updated it locally, are trivial: everything will be fine and you would not even notice.

The cases where you changed summary, description or even the icon via web, but didn’t update them locally will just generate a conflict on the next upload, and you would need to do the updating (or forcing the Store state to what you have locally, with --force-metadata).

An inconvenient arises for screenshots. As this field was not supported in the YAML before this whole “update metadata” feature, developers were forced to change them via web, and WILL NOT have the updates locally. At some point, snapcraft is updated, and it starts complaining about something that before the update was not supported.

For the first upload after snapcraft is updated, we can behave in two ways:

  • just present a conflict situation (as with the other fields): it’s the simplest and more consistent thing to do, but it would be a nuisance to the developer: she would be forced to find out where are now those screenshots she took a while ago (or go to the web ui and re-download them) if wants to keep them, or force the metadata update, which would remove the screenshots server side.

  • only modify the screenshots server side if a field was actually included in the YAML: so in the transition nothing would happen, and we would start updating screenshots when the developer starts including them in the YAML file. This brings two complexities, though:

    • the simplest one is that we’re kind of ignoring a sync case. Maybe snapcraft could (in the case of finding that the server has screenshots but locally are not declared) put a message to the user alerting the situation and telling she can include screenshots locally.

    • the more complicated one is how the semantics would be for the developer to express in the YAML file that all screenshots should be removed. This special case can be flaged if screenshots: [] is included in the YAML, which will make the request to the server to also include it empty, and the server would remove the metadata for this. It’s not something difficult to do, just a corner case that would imply more documentation and explanations for developers.

We’re still defining these details, any feedback is welcomed!

Thanks in advance!

1 Like

I like the second option as it is less of a nuisance to the developer, as you say. I think screenshots: [] is reasonable as a way to delete screenshots, which I think will not be used very often, and what you could do is include this in the “you can include screenshots in your snapcraft.yaml - please see http://wherever.com for more details”, and very specifically put a “deleting all server-side screenshots” section there explaining how to do this with this “magical” syntax. Screenshot syntax will be new and will require documentation anyway, so I don’t think this is terrible.

My initial fear was that, given the option to not change the screenshots, most developers will do just that, and the old screenshots will remain forever and ever, whereas your first option kind of forces developers to acknowledge screenshots as metadata that needs to be kept up to date, but I think the cost of breaking the flow with a non-conflict conflict is too high.