flathub-infra / documentation Goto Github PK
View Code? Open in Web Editor NEWDocumentation for flathub
Home Page: https://docs.flathub.org/
Documentation for flathub
Home Page: https://docs.flathub.org/
On this page:
https://github.com/flathub/flathub/wiki/App-Requirements
Can you please provided a demo document showing a bare minimum of a setup that would get approved? That way a template is provided for new developers to sample from.
Would be great, if @barthalion could feed some search engines with https://docs.flathub.org/sitemap.xml
These are parts that we want to happen in the new docs, not necessary as those pages:
For users
For app developers
For reviewers
There should be something that explains how they work in flathub
How are they different from regular apps? What requirements do they have? What do normal apps require to integrate them? Do they need to go thought the normal submission process?
A minor thing I noticed. I decided to open an issue instead of PR, because maybe its on purpose? But it seems weird:
The brand color section in the quality guidelines links to itself in the first sentence: https://docs.flathub.org/docs/for-app-authors/metainfo-guidelines/quality-guidelines/#brand-colors
We do not have any instructions on this anywhere, which is not nice of us.
We have a couple of stub pages for two approaches:
But there's not really an overview of how to automate publishing updates to Flathub apps—and how each approach differs.
I imagine we want to recommend external-data-checker over uploading binaries with the GitHub Action since the former gets reproducible builds on our infra and multiple architecture builds?
Raised on Mastodon: https://hachyderm.io/@edfloreshz/111988883705161333
We could link to the Matrix channel and Discourse as a couple of options for people asking for advice re: MetaInfo.
Build: https://buildbot.flathub.org/#/builders/5/builds/14379
Documentation: https://docs.flathub.org/docs/for-app-authors/linter/#module-module_name-source-git-branch
yaml: https://github.com/flathub/io.github.tlcfem.suanPan/pull/43/files
It seems okay and is aligned with the documentation, what does this error mean?
Hi!
In the past, we used the "provides" tag to make replacements/renames of tags work for components.
This is documented at https://docs.flathub.org/docs/for-app-authors/appdata-guidelines/#provides
The provides tag basically means "component B provides all interfaces of component A", for example, org.freedesktop.pipewire
could provide org.freedesktop.pulseaudio
. This is of course the case when an ID is renamed, and initially we thought this was "good enough". It did yield some dumb errors though, and generally was confusing to handle for software centers, as there is a semantic difference between "this component provides all interfaces of the other component, but both exist and are valid" and "this component provides all interfaces of the other component, because the latter is dead and can no longer be installed".
This is also important for properly moving ratings & reviews between a component taking over another.
So, since 2022, AppStream supports a proper replaces
tag to handle component IDs being renamed. It is defined here: https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-replaces
All AppStream versions >= 0.15.5 support it.
The problem is that this tag was never supported by appstream-glib, and most certainly will never be supported by it either.
So I don't know if we can make this switch, but I would very much like to see it once we can make it happen - it will make life a lot easier for software stores consuming the Flatpak metadata when components are renamed.
That said, ideally any ID renames should be avoided, they will cause quite a lot of issues for popular applications.
I suspect that due to the absence of the 'developer_name' tag, certain applications might be displayed without their developer names in LTS releases like Ubuntu and Ubuntu based distros.
Biblioteca is experiencing this issue.
Tested on:
I'm not sure if this needs to be mentioned in the documentation or if it requires another action on Flathub.
https://docs.flathub.org/docs/for-app-authors/linter#linter-errors shows letters in the sources of the foot notes, but numbers before the foot notes (https://docs.flathub.org/docs/for-app-authors/linter#fn-a)
So it is not obvious which footnote is referenced. (Does 1 in xxx[b] link to 1yyy or 2 zzz or ...)
But in the preview of the source, numbers are used in both places:
https://github.com/flathub/documentation/blob/main/docs/02-for-app-authors/12-linter.md
No idea where to fix this.
There's a screenshot on this page that is unnecessarily political.
Not only that, but one of the fake contacts is Ernesto Guevara (Che Guevara), a known homophobic, racist and killer.
So I'm sure it's in Flathub's best interest not to be associated with such character.
Whenever a new runtime releases, the docs will quickly suggest outdated runtime versions. As the docs grow, so will the difficulty of manually updating each page to reflect the newest runtime version. Perhaps we could set up something that automates the process of updating runtime versions?
The landing page is a bit sad, maybe @jimmac has a moment to come up with a cool graphic to lighten it up
https://github.com/flathub/flathub/wiki/App-Requirements#stable-releases-reproducible-builds says "When building from a git tag, both the tag name and the commit id should be specified", but it doesn't say where they should be specified. To someone familiar with the process, the answer is obviously "in the sources/git section of the flatpak manifest", but to someone trying to learn (and juggling many new unfamiliar files) it's not very obvious. That could be a little clearer and more helpful if it said something like "When building from a git tag, both the tag name and the commit id should be specified in the git source in the package's flatpak manifest", perhaps.
I'd expect to see them linked from https://github.com/flathubbot
Now that GitHub allows profile READMEs this would be the perfect place to link to the bot's docs.
Hi in https://docs.flathub.org/docs/for-app-authors/updates/
The last link https://flatpak.github.io/xdg-desktop-portal/docs/#gdbus-org.freedesktop.portal.Flatpak.UpdateMonitor seems to be broken (doesn't show up in search either?) should it perhaps be this?
https://docs.flatpak.org/en/latest/portal-api-reference.html#gdbus-org.freedesktop.portal.Flatpak.UpdateMonitor
Or maybe mentioning this? https://libportal.org/method.Portal.update_install.html
Thanks
In https://github.com/flathub/flathub/wiki/App-Maintenance, the f-e-d-c options that can be added to flathub.json
should be listed and documented.
OS Linux Mint 21.2 Cinnamon
Was working fine yesterday. As far as I can tell, the issue started to occur after some Flatpak updates came in.
~$ flatpak run com.usebottles.bottles
Result:- *** stack smashing detected ***: terminated
Doesn't seem to have that rule explained:
https://docs.flathub.org/docs/for-app-authors/linter/
We should outline how app id and verification work off each other
Where to request access? How to request access? Who should be given access? The process, requirements etc.
There's no set requirement right now other than being involved with upstream or the Flathub repo or being a "known" face I guess, but still worth to document.
I don't think it's a bad idea, do you?
Can we give more guidance for figuring out categories? Are we already doing good on that?
@jimmac could you maybe find some time to come up with a nice social card?
Hi!
This is very much a nitpick, but after thinking about it a bit, I think it's important to at least think about whether it is worth to change this.
In 2014, AppStream's scope was expanded to not just include metadata about applications, but about literally any software component. Consequently, the "AppData" name was changed to "MetaInfo" to be more clear that this is metadata, and not actual application data. This also removed a name clash with the same term being used differently by Microsoft in Windows (not essential, but neat!). Then in 2017/early 2018, we completely moved from the /usr/share/appdata
location to /usr/share/metainfo
for all MetaInfo data and deprecated the old location, which was then completely removed December 2023.
Consequently, there are now only two names for AppStream data which are used without ambiguity in AppStream's documentation, tools and API:
/usr/share/metainfo
In the Flathub docs, Flathub still seems to be using the old name from 2014/2017.
TBH, I don't think it's terrible, but it is a tiny bit confusing, and maybe worth changing if that doesn't mean breaking anything.
I think the following information should be provided via appdata.
Developer name for all applications via developer_name
tag:
<developer_name translatable="no">Hayri Potur</developer_name>
Flathub does not support new developer > id tag
<developer id="github.com">
<name translatable="no">Hayri Potur</name>
</developer>
Home page URL for all applications
<url type="homepage">https://github.com/hayri/potur</url>
Bug tracker URL for almost all applications
<url type="bugtracker">https://github.com/hayri/potur/issues</url>
Repository URL for open source applications
<url type="vcs-browser">https://github.com/hayri/potur</url>
Translate URL for translatable applications: e.g:
<url type="translate">https://github.com/hayri/potur/tree/main/po</url>
<url type="translate">https://hosted.weblate.org/engage/hayri/</url>
Only one donation URL
<url type="donation">https://liberapay.com/xyz</url>
translation
tag for translatable applications: e.g:
<translation type="gettext">hayri</translation>
launchable
tag for non-cli applications:
<launchable type="desktop-id">com.github.hayri.Potur.desktop</launchable>
I'm trying to make a flatpak version of OpenShot, and I couldn't find an easy way to inspect what libraries are available in org.kde.Platform or org.kde.Sdk. I would be nice if this kind of information were available in Flathub's webpage or in the Wiki somehow.
https://github.com/flathub/flathub/wiki/App-Submission#how-to-submit-an-app says
A set of steps like this is often followed quite unthinkingly, by copying the commands into a terminal and running them (see also, for example, GitHub's presentation of steps to push to a new empty repository, which can be copied one-by-one and many developers do exactly that without having to think about it).
The set of steps above fails in that, because one's in the wrong directory; this could be neatly solved by having a new step "2.5" in between 2 and 3, reading:
2.5. Change to the cloned flathub repo: cd flathub
which would make the process of copying and running the commands a bit nicer for a new developer.
Now that Flathub supports showing translated metainfo for apps, I wonder if it would make sense to require basic metainfo translation support for being featured. For people who do not use English widely in their day-to-day lives, app metainfo being translated can make a huge impact on its perceived quality. Translation infrastructure is also mostly a technical endeavour, and requiring developers to at least make it possible to submit translations to the app metadata with .po files or a service like Weblate, doesn't seem unreasonable to me. The amount/coverage of translations shouldn't have anything to say as long as it's possible to contribute to them.
This is definitely not worth it if it requires a manual inspection for each app, though. Here are some ways we might be able to control it automatically:
metainfo.xml
and appdata.xml
in the po/POTFILES
list in the app's source code repository (only works for apps that use gettext)translation
AppStream tag somehowI think we need to document for normal users, when they would need to change app sandbox permissions and how to do that.
So at least have a guide on how to change sandbox permissions with:
I believe that keywords are also extracted from the desktop files. Can we modify the following sentences?
Icons and categories
If there’s a type="desktop-id" launchable, they get pulled from it. Most of the icon not found errors with the flathub builder can be traced down to the launchable value not matching the desktop file name.
Don’t set them in the AppData unless you want to override them (even though then it might be a better idea to patch the desktop file itself).
Source: https://docs.flathub.org/docs/for-app-authors/appdata-guidelines/#icons-and-categories
From https://docs.flathub.org/docs/for-users/user-vs-system-install/
Per-user installations are recommended for most users, unless they have a specific reason to use system-wide installations.
If it's recommended, then why don't we mention that in the Setup Flatpak pages?
From the Debian page:
It could be just a link for more information. Otherwise most users will be installing system-wide.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.