Update legacy app framework documentation to be Flatpak-friendly

This is not entirely complete, but it's being posted here for initial feedback.

In particular, there were some questions I built up over the course of making these changes, where the answers impact more updating:

• How should "built-in" applications be changed? How these would be handled in the future seems undecided... I can opt for just removing the references, and then if/when this is more concrete, re-add them back. (Or should the different approaches mentioned in the Mattermost be placed here for discussion purposes?)
• Is app installation tracking still a goal?
• The "Permissions concept design" document is all talking about something that was never implemented. However, it does still feature interesting discussion, so I'm planning on just moving things around to make clear that Flatpak's permissions model was chosen. Would this work, or should it be more severely gutted?
• Does the "application manager" concept still exist? It seems like it's largely eclipsed by portals & misc. other components.
• How do "System Extensions" fit into the new model? They seem to be using the application bundle concept to extend the host system, i.e. not other bundles, but this isn't really something that Flatpak can do?
• How does persisting applications across system restarts fit into the new model? Is this still planned at all?
  • Same question for "frozen" applications (faster start-up time than a dead application without using the equivalent background resources).
• Is the state-saving convenience API still planned?
• Are X-Apertis- keys still a thing?

In some places I did err on the side of removing things, simply because the original information is always in the Git history and can be added back.

I do also plan on completely removing:

• The app bundle specification.
• The structure document.

since these are all essentially covered purely by Flatpak, and the current pages have very little to add that could be kept. However, I did want to mention it here first just in case there's debate on that.

https://phabricator.apertis.org/T7987

Signed-off-by: Ryan Gonzalez ryan.gonzalez@collabora.com

changed the description

• How should "built-in" applications be changed? How these would be handled in the future seems undecided... I can opt for just removing the references, and then if/when this is more concrete, re-add them back. (Or should the different approaches mentioned in the Mattermost be placed here for discussion purposes?)

I think the concept of built-in apps (pre-installed flatpaks) is something we'd want to keep, so I would just reword it as needed - one possible solution would be to preinstall flatpaks in the images/ospack directly as we do for the reference runtimes/demos.

• Is app installation tracking still a goal?

I think it would still be useful, specially as a concept (i.e. currently not implemented).

• The "Permissions concept design" document is all talking about something that was never implemented. However, it does still feature interesting discussion, so I'm planning on just moving things around to make clear that Flatpak's permissions model was chosen. Would this work, or should it be more severely gutted?

Yes, I think that is a good approach.

• Does the "application manager" concept still exist? It seems like it's largely eclipsed by portals & misc. other components.

Agree it is eclipsed by portals and flatpak itself.

• How do "System Extensions" fit into the new model? They seem to be using the application bundle concept to extend the host system, i.e. not other bundles, but this isn't really something that Flatpak can do?

My feeling is we should drop it.

• How does persisting applications across system restarts fit into the new model? Is this still planned at all?

Unsure what you mean but if referring to the following I would just drop it:

For more invasive system extensions, the application manager can decide
based on the extension type in the application bundle metadata whether the
functionality requires that the system be restarted.

• Same question for "frozen" applications (faster start-up time than a dead application without using the equivalent background resources).

Does flatpak supports something like this? If not I would drop it.

• Is the state-saving convenience API still planned?

I would drop it as not supported by Flatpak, but it seems a useful feature though.

• Are X-Apertis- keys still a thing?

No.

In general my feeling is that if something is not supported by flatpak we should just drop it and maybe re-add a later point if we find the need again. Or if we keep it make it explicit flatpak doesn't support it and would need to be implemented.

@em would love to hear your thoughts here as well.

added 1 commit

• 581ba771 - Update legacy app framework documentation to be Flatpak-friendly

Compare with previous version

added 1 commit

• ed53e790 - Update legacy app framework documentation to be Flatpak-friendly

Compare with previous version

added 1 commit

• 9ca1e6d7 - Initial updates legacy appfw documentation for Flatpaks

Compare with previous version

resolved all threads

I've gone over all of the referenced documents again, and I believe with this change, at least 80% of it should be updated (assuming I missed some more subtle sections). Regardless, I'm removing the draft status now, because remaining bits could be migrated in later MRs. (I did completely nuked application-structure, because that was far too Canterbury-specific IMO.)

The main outstanding question is how to handle "Platform APIs and Services". It draws a dividing line between "SDK APIs" and "Enabling APIs", but a large number of the former seem to be dead now. If there's any document that should be largely gutted, maybe it would be that one?

marked this merge request as ready

mentioned in merge request !366 (merged)

Ok, this is really hard to review/parse as too big, but had a look in general and looks good so I think we should land this and have another look at the updated docs after that. But before we land, let's make sure we update/drop any pending TODO items (there is at least one left) and also drop the bundle-spec document.

added 1 commit

• 5ad085d2 - Initial updates to legacy appfw documentation for Flatpaks

Compare with previous version

added 1 commit

• c59ebe1c - Initial updates to legacy appfw documentation for Flatpaks

Compare with previous version

resolved all threads

approved this merge request

added 39 commits

• c59ebe1c...f0bc3dbc - 38 commits from branch master
• f25b84d0 - Initial updates to legacy appfw documentation for Flatpaks

Compare with previous version

resolved all threads

approved this merge request

enabled an automatic merge when the pipeline for f25b84d0 succeeds

merged