flathub-infra / flatpak-builder-lint

A linter for flatpak-builder manifests

flatpak-builder-lint

flatpak-builder-lint is a linter for flatpak-builder manifests, and more widely, also Flatpak builds. It is primarily developed for Flathub, but can be useful for other Flatpak repositories.

Installation

The only supported ways to install and use it are Docker and Flatpak.

Docker

The latest build of flatpak-builder-linter can be used with Docker.

docker run --rm -it ghcr.io/flathub/flatpak-builder-lint:latest

You may need to pass the local data using --volume to check the chosen file or repo.

Flatpak

flatpak-builder-lint is part of the org.flatpak.Builder flatpak package available on Flathub. Set up Flatpak first, then install org.flatpak.Builder:

flatpak install flathub -y org.flatpak.Builder
flatpak run --command=flatpak-builder-lint org.flatpak.Builder --help

The flatpak package tracks the git commit currently used on the Flathub infrastructure.

Local environment

Installing flatpak-builder-lint locally with Poetry or pip is not recommended unless for development purposes. It depends on patches that are found in the org.flatpak.Builder flatpak package and on external tools.

git clone https://github.com/flathub/flatpak-builder-lint
cd flatpak-builder-lint
poetry install 
poetry run flatpak-builder-lint --help

Additional tools are required by subcommands and checks:

• flatpak-builder for validating flatpak-builder manifests,
• ostree for validating ostree repositories containing builds,
• appstreamcli from org.flatpak.Builder for validating MetaInfo files,
• desktop-file-validate to validate desktop files.

Usage

usage: flatpak-builder-lint [-h] [--version] [--exceptions] [--appid APPID] [--cwd] [--ref REF] {builddir,repo,manifest,appstream} path

A linter for Flatpak builds and flatpak-builder manifests

positional arguments:
  {builddir,repo,manifest,appstream}
                        type of artifact to lint
  path                  path to artifact

options:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  --exceptions          skip allowed warnings or errors
  --appid APPID         override app ID
  --cwd                 override the path parameter with current working directory
  --ref REF             override the primary ref detection

If you consider the detected issues incorrect, please report it here: https://github.com/flathub/flatpak-builder-lint

Documentation

A list of errors and warnings and their explanations are available in the Flatpak builder lint page.

flatpak-builder-lint's Issues

module-{name}-cmake-non-release-build has too much false-positives

It doesn't treat MinSizeRel and random values as release builds. The latter is actively used to prevent falling back to a project-defined default CMAKE_BUILD_TYPE and don't have additional C(XX)FLAGS set by cmake. The right way is check whether the value is Debug, that's also how most cmake projects check to insert their own debug flags.

finish-args-arbitrary-dbus-access for Elisa

See: https://buildbot.flathub.org/#/builders/37/builds/2712

This is being proposed in flathub/org.kde.elisa#89, because it's required for a feature of the app to work.

Warnings cause pipeline crashes

Traceback (most recent call last):
  File "/app/bin/flatpak-builder-lint", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/app/lib/python3.11/site-packages/flatpak_builder_lint/cli.py", line 148, in main
    if args.exceptions and not args.json:
                               ^^^^^^^^^
AttributeError: 'Namespace' object has no attribute 'json'

See this build:
https://buildbot.flathub.org/#/builders/6/builds/71934

Question: Purpose of `flathub-json-modified-publish-delay`

flathub-json-modified-publish-delay started firing for repository I'm maintainer of but I can't find any explanation on why overriding publish-delay-hours below 3h is prohibited? And only if there aren't any extra-data sources?

Examples on documentation page https://github.com/flathub/flathub/wiki/App-Maintenance doesn't have any details and even example is about publishing more often.

cmake-no-debuginfo is bogus warning

Right now linter checks for -DCMAKE_BUILD_TYPE=Release and warns about supposedly missing debuginfo. This is misleading since cmake inherits -g from default CFLAGS environment which means Release has same amount of debuginfo as RelWithDebInfo has.

The actual difference is in optimization level -O3 vs -O2 which is different matter.

Missing `finish-args` isn't an error for extensions

We should check if build-extension is not set to True before proceeding to validate finish-args.

Add basic appdata quality checks

We have new appdata quality guidelines now, some of which could be relatively easily checked in an automated way, including:

• Icon fills the entire canvas (no transparent pixels)
• Icon is a symbolic (i.e. all non-transparent pixels are the same color)
• Summary ending with dot (".")
• Name >20 characters
• Summary >35 characters
• No screenshot captions
• Developer field is not empty

False positive finish-args-unnecessary-appid-own-name?

A test build of PR Update to LibreOffice 7.4.2 initiated earlier today failed at https://buildbot.flathub.org/#/builders/19/builds/19 with

flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions org.libreoffice.LibreOffice.json
 in dir /srv/buildbot/worker/build-x86_64-1/build (timeout 1200 secs)
 watching logfiles {}
 argv: b'flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions org.libreoffice.LibreOffice.json'
 using PTY: False
{
    "errors": [
        "finish-args-unnecessary-appid-own-name"
    ]
}
If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint
program finished with exit code 1

I assume the linter complains about the line https://github.com/flathub/org.libreoffice.LibreOffice/blob/ebf2dbae06f39e50be7d62e11eed6e8724a109c5/org.libreoffice.LibreOffice.json#L724

        "--own-name=org.libreoffice.LibreOfficeIpc0",

but it is unclear to me why it does that. (And removing that line from the manifest would break the resulting LibreOffice, it would no longer start.)

Linter crashes due to reference to args.json

In 93d267a args.json was removed, however the reference on line 148 was missed, and this is now raising AttributeError. This issue blocks CI when the linter reports warnings.

Example: https://buildbot.flathub.org/#/builders/25/builds/8845

Don't use hyphens in python module names

While such modules are still importable by their string names with importlib, they aren't importable as normal modules with import statements. It's usually suggested to use valid module names for all python project files except for entrypoint.
Suggestion: rename finish-args.py to finish_args.py

autotools-non-release-build ?

Can someone tell me what this means?

flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions com.dosbox_x.DOSBox-X.yaml
 in dir /srv/buildbot/worker/build-x86_64-5/build (timeout 1200 secs)
 watching logfiles {}
 argv: b'flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions com.dosbox_x.DOSBox-X.yaml'
 using PTY: False
{
    "errors": [
        "module-dosbox-x-autotools-non-release-build"
    ]
}
If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint
program finished with exit code 1
elapsedTime=1.308365

flathub/com.dosbox_x.DOSBox-X#10

Filter or reject AppStream metadata with invalid icons

cc.nift.nsm currently has AppStream metadata with:

 <icon height="128" width="128">$APPID.png</icon> 
 <icon height="64" width="64">$APPID.png</icon> 

(flathub/cc.nift.nsm#3)

This seems wrong in a couple of ways: libappstream warns on reading this (although apparently appstream-glib considers it to be perfectly valid?), and apps probably also shouldn't be allowed to specify an icon name that is outside their namespace.

The maintainer of libappstream says this is something that Flatpak and/or Flathub should be preventing:

There seems to be something wrong with Flatpak's or Flathub's
AppStream generator (even if the input is bad, the output of the
server shouldn't be bad too!)

(But I don't think validating AppStream is really Flatpak's or flatpak-builder's job, and it seems more appropriate for this to be something that Flathub is responsible for.)

Build 3287 failed

Hi,
I'm trying to push an update, here: [(https://github.com/flathub/com.icanblink.blink/pull/5)]

Build works perfectly on my local pc, so can someone enlighten me on what I need to change?

Thanks.

Allow git:// URLs

Is there a particular reason why git:// URLs are not allowed?

https://github.com/flathub/flatpak-builder-lint/blob/f04c0cef5db922fb872c915e28bfa58f5778f19f/flatpak_builder_lint/checks/modules.py#L43

This blocks e.g. this PR: https://github.com/flathub/io.qt.QtCreator/pull/89/files

finish-args-unnecessary-xdg-data-access

My app (LibreMines) needs access to the directory ~/.local/share/libremines so it can save scores, user configs and load custom minefield themes.

For that, I used the finish-arg: "--filesystem=xdg-data/libremines:create",.

For some reason, the build is failing on the part of check manifest, as shown here.

flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions io.github.Bollos00.LibreMines.json
 in dir /srv/buildbot/worker/build-x86_64-4/build (timeout 1200 secs)
 watching logfiles {}
 argv: b'flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions io.github.Bollos00.LibreMines.json'
 using PTY: False
{
    "errors": [
        "finish-args-unnecessary-xdg-data-access"
    ]
}
If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint
program finished with exit code 1
elapsedTime=0.588067

I do not understand the issue, should this file be changed like this?

Build suddenly fails with jsonschema-validation-error

I'm the maintainer of eu.betterbird.Betterbird and noticed that builds started to fail today because of the following error:

flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions eu.betterbird.Betterbird.json
 in dir /srv/buildbot/worker/build-x86_64-4/build (timeout 1200 secs)
 watching logfiles {}
 argv: b'flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions eu.betterbird.Betterbird.json'
 using PTY: False
{
    "errors": [
        "jsonschema-validation-error"
    ],
    "jsonschema": [
        "{'dest': 'cargo/vendor/atty-0.2.14', 'url': 'data:%7B%22package%22%3A%20%22d9b39be18770d11421cdb1b9947a45dd3f37e93092cbf377614828a319d5fee8%22%2C%20%22files%22%3A%20%7B%7D%7D', 'dest-filename': '.cargo-checksum.json', 'type': 'file'} is not valid under any of the given schemas"
    ]
}

The .json that causes the error used to work fine and I have not changed it, so I figured the linter must have changed.

@Erick555 FYI You should see the same behavior for org.mozilla.Thunderbird because you are using the same cbindgen-sources.json file. Can you confirm that?

jsonschema error

I'm trying to update the runtime of the Karapulse package: flathub/org.karapulse.Karapulse#16

Build failed here: https://buildbot.flathub.org/#/builders/19/builds/1575

{
    "errors": [
        "jsonschema-validation-error"
    ],
    "warnings": [
        "module-karapulse-source-sha1-deprecated",
        "finish-args-contains-both-x11-and-wayland"
    ],
    "jsonschema": [
        "{'dest': 'cargo/vendor/addr2line-0.13.0', 'url': 'data:%7B%22package%22%3A%20%221b6a2d3371669ab3ca9797670853d61402b03d0b4b9ebf33d677dfa720203072%22%2C%20%22files%22%3A%20%7B%7D%7D', 'dest-filename': '.cargo-checksum.json', 'type': 'file'} is not valid under any of the given schemas"
    ]
}
If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint

The exact same manifest used to work fine, see flathub/org.karapulse.Karapulse#15 , so I guess this may be a false positive?

Easier local installation

I'd like to run this tool locally so that I can attempt to fix its errors without constant pushes to Flathub git. I wonder if you could submit this tool to PyPI? That would make local installation easier than running it from a dev environment. Alternatively, for example flatpak-external-data-checker provides a flatpak-based installation, perhaps something like that would be an option here as well?

Thanks!

Add exception file JSON validation

CI should at least check that the exception file is valid JSON. See #73 for a justification.

Investigate if `org.freedesktop.portal.*` permissions are needed

Afaiu, these are allowed by flatpak itself https://github.com/flatpak/flatpak/blob/f66b1ecb7420ba56bc57cada92a1ed01a5a330f9/common/flatpak-run-dbus.c#L290-L294 and there should be no reason to put a --talk-name to them in app manifest since that allows for wider access than what flatpak gives by default.

Around ~36 apps are using it based on a Github search

The most common one being org.freedesktop.portal.Fcitx which seems to have originated from a fcitx bug back in 2018 flatpak/flatpak#2031 and since been fixed on fcitx 4.2.9.7 (even Debian oldstable has newer fcitx than that https://packages.debian.org/search?keywords=fcitx&searchon=names&suite=all&section=all)

Another one popular one seems to be the background portal which seems to be not required at all to keep the app alive eg. flathub/org.signal.Signal#524

I think these should be error-ed by default in the linter

Error: arbitrary-autostart-access. Unable to publish an update

My app pre-loads itself in memory on startup.

This increases performance on some older devices.
How can I fix this issue?

App: https://github.com/mijorus/smile

[view all 16 lines](https://buildbot.flathub.org/#/builders/30/builds/227/steps/6/logs/stdio) 
flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions it.mijorus.smile.json
 in dir /srv/buildbot/worker/build-aarch64-3/build (timeout 1200 secs)
 watching logfiles {}
 argv: b'flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions it.mijorus.smile.json'
 using PTY: False
{
    "errors": [
        "finish-args-arbitrary-autostart-access",
        "finish-args-unnecessary-xdg-config-access"
    ]
}
If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint
program finished with exit code 1
elapsedTime=0.459918

Failing build checks for xdg-config access

Using --filesystem=xdg-config causes failing for build checks. Below is the error given from the flathub buildbot.

flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions org.cubocore.CoreAction.yml
 in dir /srv/buildbot/worker/build-x86_64-6/build (timeout 1200 secs)
 watching logfiles {}
 argv: b'flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions org.cubocore.CoreAction.yml'
 using PTY: False
{
    "errors": [
        "finish-args-arbitrary-xdg-config-access"
    ]
}
If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint
program finished with exit code 1
elapsedTime=0.638376

org.kde.kontact is suddenly unbuildable

flathub complains about

"finish-args-unnecessary-appid-own-name"

Please make it stop complaining about that :)

url is a zero length file

I maintain a flatpak in https://github.com/flathub/com.github.makhber.Makhber
the latest PR failed with:

uilddir/files/share/appdata/com.github.makhber.Makhber.appdata.xml: FAILED:
• file-invalid          : <screenshot> url is a zero length file [https://github.com/Makhber/makhber/raw/master/screenshots/Screen1.png]
• file-invalid          : <screenshot> url is a zero length file [https://github.com/Makhber/makhber/raw/master/screenshots/Screen2.png]

but they are not.

Extend xdg-* checks to catch subdirectories

As displayed by https://github.com/flathub/flathub/pull/3653/files#diff-7449d1d793006d078d8ec22550b1b85050f5dc864fb356154923fa08278ab3b8R18, we should probably lint any combination of xdg-* and subdirectories.

Add exception for io.github.Youda008.DoomRunner

Build for the new app io.github.Youda008.DoomRunner is failing due the "finish-args-flatpak-spawn-access" error.
Please add an exception.

For an explanation about reasons please take a look at this comment.

finish-args-broken-kde-tray-permission is incorrect

The finish-args-broken-kde-tray-permission forbids anything with org.kde.StatusNotifierItem at the beginning, however this isn't correct.

As you can see in knotification: https://github.com/KDE/knotifications/blob/7fb8c5b3130646845efb0483fc1cf3c7769c5830/src/kstatusnotifieritemdbus_p.cpp#L134

This is a unchanging format. In flatpak it will always be the same value for the same pid for the same item number.

Now this is very broken inside of flatpak but it is the correct permission to say --own-name=org.kde.StatusNotifierItem-2-1 because you know your values will always be the same. Fixing it means patching KDE libraries but that's a discussion for other people.

Failure with io.mpv.Mpv.yml

io.mpv.Mpv builds fine and runs fine on my debian system. flathub buildbot gives not so helpful message.

flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions io.mpv.Mpv.yml
 in dir /srv/buildbot/worker/build-x86_64-5/build (timeout 1200 secs)
 watching logfiles {}
 argv: b'flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions io.mpv.Mpv.yml'
 using PTY: False
{
    "errors": [
        "module-pipewire-jack-runtime-source-git-branch",
        "module-luajit-source-git-branch"
    ],
    "warnings": [
        "module-uchardet-cmake-no-debuginfo",
        "finish-args-contains-both-x11-and-wayland",
        "module-x265-buildsystem-is-plain-cmake",
        "module-x265-cmake-no-debuginfo",
        "module-x265-source-md5-deprecated"
    ]
}
If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint
program finished with exit code 1
elapsedTime=0.337740

appid-code-hosting-too-few-components error backwards compatibility?

Hey,

I recently ran into this linting issue;

{
    "errors": [
        "appid-code-hosting-too-few-components"
    ]
}

Not sure what to do now. Should the entire app be migrated to another domain, like com.ezquake.ezQuake or com.github.QW-Group.ezQuake?

I don't like flathub-json-eol-rebase-misses-new-id

On flathub/org.gnome.dfeet#19 I tried to add the following flathub.json to dfeet:

{
    "end-of-life": "This application is no longer maintained and is superseded by D-Spy.",
    "end-of-life-rebase": "org.gnome.dspy"
}

The linter rejected this because flathub-json-eol-rebase-misses-new-id. The check is:

https://github.com/flathub/flatpak-builder-lint/blob/fc76448d5539fb6a42f1a0b6f4a8982beef17c9e/flatpak_builder_lint/checks/flathub_json.py#L36-L38

So the end-of-life message has to include the literal app ID that is specified as end-of-life-rebase.

I don't really see why this is necessary. The app ID is present in a machine-readable form already so it's redundant. Is it not better to have the human-readable name of the app in the message?

redundant-prefix warnings don't check for paths

https://github.com/flathub/org.gnome.Totem.Devel/blob/beta/codecs/ffmpeg.json uses:

    "config-opts": [
        "--prefix=/app/lib/codecs/",
        "--libdir=/app/lib/codecs/lib",

which the linter warns about:

    "warnings": [
        "module-ffmpeg-autotools-redundant-prefix"
    ]

But the paths are different, so aren't redundant.

Why does using plain cmake cause a warning?

Hi there, I'm the maintainer of https://github.com/flathub/org.openhantek.OpenHantek6022 - I was doing some maintenance on it today and the build omitted the warning module-openhantek-buildsystem-is-plain-cmake. I'm trying to understand why this is a bad thing, as I can't find anything in the Flatpak docs saying I shouldn't be using cmake?

finish-args-redundant-device-all not useful

https://github.com/flathub/org.gnome.Totem.Devel/blob/beta/codecs/ffmpeg.json uses:

        /* OpenGL access */
        "--device=dri",
        /* DVD playback */
        "--device=all",

Which triggers the error finish-args-redundant-device-all. But the --device while redundant is a good documentation. The error should warn for duplicate --device flags instead.

jsonschema is not valid under any of the given schemas

https://buildbot.flathub.org/#/builders/25/builds/262

{
"errors": [
"jsonschema-validation-error"
],
"warnings": [
"module-allegro-buildsystem-is-plain-cmake"
],
"jsonschema": [
"{'dest': '.dub/packages', 'url': 'data:%5B%7B%22name%22%3A%20%22allegro%22%2C%20%22version%22%3A%20%224.0.4%2B5.2.0%22%2C%20%22path%22%3A%20%22%40builddir%40/.flatpak-dub/allegro-4.0.4%2B5.2.0%22%7D%2C%20%7B%22name%22%3A%20%22bolts%22%2C%20%22version%22%3A%20%221.3.1%22%2C%20%22path%22%3A%20%22%40builddir%40/.flatpak-dub/bolts-1.3.1%22%7D%2C%20%7B%22name%22%3A%20%22derelict-enet%22%2C%20%22version%22%3A%20%224.2.0%22%2C%20%22path%22%3A%20%22%40builddir%40/.flatpak-dub/derelict-enet-4.2.0%22%7D%2C%20%7B%22name%22%3A%20%22derelict-util%22%2C%20%22version%22%3A%20%223.0.0-beta.2%22%2C%20%22path%22%3A%20%22%40builddir%40/.flatpak-dub/derelict-util-3.0.0-beta.2%22%7D%2C%20%7B%22name%22%3A%20%22enumap%22%2C%20%22version%22%3A%20%220.4.2%22%2C%20%22path%22%3A%20%22%40builddir%40/.flatpak-dub/enumap-0.4.2%22%7D%2C%20%7B%22name%22%3A%20%22optional%22%2C%20%22version%22%3A%20%221.3.0%22%2C%20%22path%22%3A%20%22%40builddir%40/.flatpak-dub/optional-1.3.0%22%7D%2C%20%7B%22name%22%3A%20%22sdlang-d%22%2C%20%22version%22%3A%20%220.10.6%22%2C%20%22path%22%3A%20%22%40builddir%40/.flatpak-dub/sdlang-d-0.10.6%22%7D%2C%20%7B%22name%22%3A%20%22taggedalgebraic%22%2C%20%22version%22%3A%20%220.11.22%22%2C%20%22path%22%3A%20%22%40builddir%40/.flatpak-dub/taggedalgebraic-0.11.22%22%7D%2C%20%7B%22name%22%3A%20%22unit-threaded%22%2C%20%22version%22%3A%20%220.7.55%22%2C%20%22path%22%3A%20%22%40builddir%40/.flatpak-dub/unit-threaded-0.7.55%22%7D%5D', 'dest-filename': 'local-packages.json', 'type': 'file'} is not valid under any of the given schemas"
]
}

flathub/com.lixgame.Lix#1 builds locally just fine. I don't understand this convoluted error message.

flatpak-manifest.schema.json is missing 'secret-opts'

One of the errors that flatpak-builder-lint lists is:

    "jsonschema": [
        "'secret-opts' does not match any of the regexes: '^//.*', '^x-.*'"
    ]

However, secret-opts and secret-env are documented keys in the flatpak-manifest manfile:

       secret-opts (array of strings)
           This is an array of options that will be passed to configure, meant to be
           used to pass secrets through host environment variables. Put the option
           with an environment variables and will be resolved beforehand.
           '-DSECRET_ID=$CI_SECRET'

For context, they were added by this PR: flatpak/flatpak-builder#408

Exception to flathub-json-skip-appstream-check error application

Hi 👋

The Flatpak build in flathub/org.getzola.zola#4 is failing because it doesn't pass the "flathub-json-skip-appstream-check" check as we skip the Appstream metainfo check since we can't pass it by the nature of being a CLI application which we can't really have meaningful screenshots of. I asked about this in the Flatpak Matrix channel, and I was told to create an issue here to apply for an exception.

Exception for Mattermost beta release versioning

Hi,

I'd like to have an exception for com.mattermost.Desktop on beta branch that is automatically released by the CI. Mattermost versioning scheme is like 5.2.1, 5.2.2-rc.1, 5.2.2-rc.2 and final 5.2.2 and this makes automatic PRs (flathub/com.mattermost.Desktop#67) fail on AppData problem: tag-invalid : <release> versions are not in order [5.2.2 before 5.2.2-rc.3].

Thank you.
-Petr

Ignore no debug info for build-time only modules ?

For modules which are only required during build time - usually the ones with cleanup: ['*'], I wonder if it's necessary to warn the users that they are building it without debug info since they are deleted totally from the exported result.

Flatseal requires xdg-data access

See flathub/com.github.tchx84.Flatseal#46
See https://github.com/tchx84/Flatseal/blob/master/com.github.tchx84.Flatseal.json#L14-L15

Arbitrary `xdg-cache` access isn't checked

We check for arbitrary xdg-config and xdg-data access, but no xdg-cache. I suppose it should be treated the same way.

error: module-Elmer-source-git-no-commit-or-tag

I got this error.

{
    "errors": [
        "module-Elmer-source-git-no-commit-or-tag"
    ],
    "warnings": [
        "module-SCOTCH-buildsystem-is-plain-cmake",
        "module-TBB-buildsystem-is-plain-cmake",
        "module-VTK-9-buildsystem-is-plain-cmake",
        "module-Elmer-buildsystem-is-plain-cmake",
        "module-Trilinos-buildsystem-is-plain-cmake"
    ]
}
If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint

I have the tag and commit in it. But still error in Elmer module.

    sources:
      - type: git
        url: https://github.com/ElmerCSC/elmerfem.git
        tag: release-9.0
        commit: 9352634829dfde24439000571d64438d8c683264

flathub/flathub#2992

Documentation for errors?

I just received the following build error when trying to update FreeFileSync on Flathub:

{
    "errors": [
        "finish-args-incorrect-dbus-gvfs",
        "toplevel-cleanup-debug"
    ],
    "warnings": [
        "finish-args-contains-both-x11-and-wayland",
        "flathub-json-deprecated-i386-arch-included"
    ]
}
If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint

It's great that it contains a link for reporting false positives, but it doesn't contain an obvious link for documentation of those errors. The error IDs don't tell me what the problem is. Where can I find explanation of what they mean and how to best fix them?

Can you please create the documentation (if it doesn't exist already, I can't find it) and provide a link in that error message? A lint tool which is mandatory should at least try to help the packagers understand the problem. Thank you.

What is the "finish-args-arbitrary-xdg-config-access" problem?

My app, Zapzap, needs "--filesystem=xdg-config/autostart:create" to create the boot file.
I do not understand what the problem and how to fix it.
How to define this permission correctly?

Re-evaluate how to check for commit-ish in commit/tag/branch of git modules

flatpak-builder allows arbitrary commit-ish in all three commit/tag/branch keys. We need to check at least the length of the value to ensure it's actually a commit, and someone doesn't bypass the check by putting tag/branch name in commit.

Failure when checking org.freedesktop.fwupd.json

I just get a failed build and:

{
    "errors": [
	"toplevel-cleanup-debug",
	"flathub-json-skip-appstream-check"
    ],
    "warnings": [
	"toplevel-unecessary-branch",
	"toplevel-command-is-path"
    ]
}

This isn't super helpful; I literally don't know what to do.

finish-args-contains-both-x11-and-fallback error is unnecessary

man flatpak build-finish says:

The fallback-x11 option makes the X11 socket available only if there is no Wayland socket. This option was introduced
in 0.11.3. To support older Flatpak releases, specify both x11 and fallback-x11. The fallback-x11 option takes
precedence when both are supported.

So there is no harm in doing so. I slightly resent having to do the busywork of deleting a harmless line in every random old app I maintain, particularly when the Flatpak documentation actively recommends the opposite. (Admittedly only to support pre-1.0 versions of Flatpak, i.e. pre-Aug 20, 2018.)

If one were feeling really keen this error could be made conditional on the app's minimum required Flatpak version…

The "test-commands" miss checking value's type

When flathub's CI tries to build com.hack_computer.Clubhouse, it shows test-commands of the manifest "com.hack_computer.Clubhouse.json" should be a string:

$ flatpak run --command=flatpak-builder-lint org.flatpak.Builder --exceptions com.hack_computer.Clubhouse.json
{
    "errors": [
        "jsonschema-validation-error"
    ],
    "jsonschema": [
        "['meson test --timeout-multiplier=10 --print-errorlogs'] is not of type 'string'"
    ]
}

If you think problems listed above are a false positive, please report it here:
  https://github.com/flathub/flatpak-builder-lint

However, according to test-commands' description: "Array of commands to run during the tests.", the value should be an array of strings.

finish-args-unnecessary-xdg-data-access is incorrect

The error means that the finish arg for xdg-data with a :create option at the end is not necessary since xdg dirs already exist. However, in this case I have an args that create subdirectories in the xdg-data dir.

--filesystem=xdg-data/backgrounds:create
--filesystem=xdg-data/gnome-background-properties:create

There should be no error for this as far as I understand.

What's the reason for the `appid-uses-code-hosting-domain` warning?

I understand, that a Homepage should be used as App ID instead of the code hosting platform, if one exists. But many Apps did not have one, so they just use the code hoster as App ID. Why did this throw a warning? It's the only valid App ID in this cases. flatpak-builder-linter should never throw a warning (even if it is a warning and not a error) on a valid App ID.

Ignoring no commit or tag when shallow clone is disabled for git source ?

In flathub/net.rpcs3.RPCS3, we build a custom upstream fork of LLVM containing some specific patches for the application. As part of the build process, they are expecting the https://github.com/intel/ittapi repo to be cloned locally and are doing a git checkout of the expected version on it. So we need it to be fully cloned as part of the build process.

I was wondering if disabling this rule for git source that are not shallow cloned should be the default, as it's made to handle this type of build. Another alternative would be to add an exception for this repository.