Change naming convention for Flatpak manifest files

[janopae]

Currently, the docs propose to name the manifest file {appliction-id}.yaml or {appliction-id}.json. This makes sense when a repository (or directory) contains multiple manifests for different applications.

However, the docs also propose to use this naming convention for their example, where the Flatpak manifest lives directly with the application itself in the same directory.

In such a case, this kind of file name is not very helpful: The information to which application the manifest belongs is already provided by the location of the file (the VCS repository) and by its contents (which also contains the application id). At least the file name provides the information that it is in yaml/json format, but it says nothing about its structure or meaning in the context of the repository.

This has the following disadvantages:

• developers who don't know about Flatpak have a hard time finding out what the file is for. The best they could do would be asking ChatGPT or a human.
• IDEs have a hard time providing autocompletion
• finding Flatpak manifests in an unknown repo can be hard (both manually and for scripts)

I propose the following convention instead:

If the target of the Flatpak manifest is unambigous given its location (e. g. the repository it lives in), simply call it flatpak-manifest.yaml/flatpak-manifest.json. If there are multiple flatpak manifest files in the location, give it a prefix that tells it apart:

• A manifest for the nightly build of the app in the containing repo might be called nightly.flatpak-manifest.yaml
• A manifest for the dependencies that gets imported by other manifests might be called dependencies.flatpak-manifest.yaml
• A manifest living in a repo along with other manifests for different applications might be prefixed with the application id (org.example.app.flatpak-manifest.yaml)

The advantages of this naming convention:

• a user unfamiliar with Flatpak could easily look up what a .flatpak-manifest file is
• scripts and users could easily find all Flatpak manifests in a certain location
• If [Feature request]: Provide json/yaml schema for manifest file via schemastore.org flatpak-builder#555 got implemented, this naming convention would automatically give us autocompletion in most IDEs for free

[TingPing]

I'll just copy my comment from the flatpak-builder issue:

Unfortunately there is a ton of convention and tooling that expects $FLATPAK_ID.json. I don't think we should publish anything until we can actually ensure people would even be open to using a new file extension.

[janopae]

Hey @TingPing, thanks for your feedback. I didn't know that tooling depends on the exact file name, I thought, most tooling was agnostic to the exact file name (like flatpak-builder is).

Only changing the suggestion when the community is on board sounds very reasonable. What would be your indicator to know whether the community is fine with a new convention? Which tools depend on the {application-id}.yaml convention, and need to support a different convention before it can be official?

[hfiguiere]

Which tools depend on the {application-id}.yaml convention,

Flathub does.

[TingPing]

GNOME-Builder, and probably every other IDE (VSCode's extension?)

[razzeee]

Still, would be nice to have that for the tooling.

I would be interested, if @bilelmoussaoui thought about this and has some insights