-
Notifications
You must be signed in to change notification settings - Fork 2k
App Requirements
The goal of these requirements is to ensure that the applications hosted on Flathub are safe to use and integrate well in the desktop experience.
If you have any further questions, please ask on #flatpak
on ircs:https://chat.freenode.net
All content hosted on Flathub must allow legal redistribution, and the license must be
correctly specified in the app's appdata file. Non-redistributable files can be downloaded at install time
using the extra-data
source type.
Each application should have a unique application ID, following the standard reverse-DNS schema. See the Flatpak documentation for more information on this.
The manifest must be at the top level and named after the application ID with the extension .json. All patches and data files required also go in the repository.
Flathub only hosts stable application releases, and not development snapshots. Manifests should therefore refer to tarballs or git tags and not the tip of a branch.
When building from a git tag, both the tag name and the commit id should be specified, like so:
"tag": "1.0.4",
"commit": "cdfb19b90587bc0c44404fae30c139f9ec1cca5c"
This ensures that the build is reproducible, since tag can change their values over time. A commit can also be specified without a tag, however tag names are encouraged as they better for readability.
Flathub always builds in the flatpak branchname "stable"
and it always passes
--default-branch=stable
. This means that a branch key doesn't need to be specified. If one is specified, it should be "stable"
.
Applications must be built against an SDK that is itself hosted on Flathub. This requirement also applies to SDK extensions that may be required in order to build an application. The easiest way to see which runtimes are currently available is to install the flathub remote and run:
flatpak remote-ls --runtime --show-details flathub
Bundled dependencies should meet the requirements on this page, including the license requirements.
Take care to check the build directory for unnecessary files. These should be added to cleanup
, in order to ensure smaller package sizes.
A small number of dependencies that are frequently used by applications have been collected in the shared-modules repository, for use by applications being distributed with flathub. These can be used as a git submodule, like so:
git submodule add https://github.com/flathub/shared-modules.git
These can be specified from manifest .json
files, like:
"modules": [
"shared-modules/SDL/SDL-1.2.15.json",
{
"name": "foo"
}
]
It is fine to patch dependencies, but please send these upstream wherever possible!
Flathub is primarily focused on graphical desktop applications and not CLI/TUI applications.
Appstream is the standard used to provide metadata about applications. Applications must provide appstream data and:
-
pass
appstream-util validate-relax
andappstream-util validate-strict
. -
include a
description
. -
include
releases
with versions and should include changelogs. -
should include OARS information, especially for games.
-
if application metadata has not been provided by the upstream, license it with Creative Commons Zero, version 1, by stating
CC0-1.0
inmetadata_license
.
For information about appstream, see its documentation.
Applications must include a desktop file and pass desktop-file-validate
.
See the desktop file spec for more details.
Applications must provide application icons at 64×64px and 128×128px sizes. Application icons should either be included as scalable SVGs or high-resolution PNGs.
The Flatpak sandbox is still a work in progress but we would still like to limit permissions
as much as possible. See man flatpak-metadata
for an overview of permissions.
The following permissions can be freely used:
--share=network
--share=ipc
--socket=x11
--socket=wayland
--socket=pulseaudio
--device=dri
Applications should not grant --socket=system-bus
or --socket=session-bus
, unless they are
development tools. The --log-session-bus
and --log-system-bus
flags can be used with flatpak run
in order to track down usage.
By default you are granted access to --own-name=$your_app_id
any ownership beyond that is
usually questionable but there are exceptions such as org.mpris.MediaPlayer2.$media_player_name
.
Talk permissions are largely unrestricted but always try to use the minimum subset needed.
Applications should ideally use Portals for file access. However, it is often necessary to grant further access. This is acceptable but should be limited as much as possible.
Additional recommendations:
-
For access to XDG directories, variables such as
xdg-music
andxdg-run/foo
are recommended (seeman flatpak-metadata
). -
Always append
:ro
if write access is not needed. -
If an application hardcodes a path in
$HOME
and you don’t granthome
access you can use--persist
and it will map the$HOME
directory to your private directory e.g.--persist=.mozilla
. If the application takes args to set config/data dirs then use them. -
Do not attempt to retain configs from non-flatpak installations. While possible it is recommended that flatpak installs stay self-contained.
-
If an application uses
$TMPDIR
to contain lock files or shared files with other process create a wrapper script that sets it to$XDG_CACHE_HOME
.
While not ideal, --device=all
can be used to access devices like controllers.
All reviews happen via comments on PR’s. We also have labels to make note the status of a PR which is useful when no actions have happened over a long period.
Once a PR has been reviewed the steps for reviewers to take after:
- Create a new repository matching the application-id under the flathub organization
- Push their latest commits to it (optionally rebase the commits)
- In Settings > Branches mark
master
as protected to preserve history - Add the author of the PR in Settings > Collaborators & Teams > Collaborators
- Close the PR linking to this new repository
A script to aid in steps 1, 2, and 5 can be found here: https://gist.github.com/TingPing/62714aea793856e42c7c556dc46caf49
Note this script does require installing gh
via npm
and does require some configuration.
Additional [guidelines on how to maintain applications that are included in Flathub](App Maintenance) are available.