[gimp-extensions-web] docs: update the README.

[Jehan <jehanp src gnome org>]

commit e893882ebaf3010ad9355248af3840a2e02ba789
Author: Jehan <jehan girinstud io>
Date:   Tue Jan 12 18:35:59 2021 +0100

    docs: update the README.
    
    There have been discussions to possibly share our existing work with
    Inkscape and FreeCAD to use the same extension format.
    Possibly even we could share a web infrastructure, benefiting everyone
    and safer maintenance (more people eyes to look at a same code, bigger
    community, etc.).
    
    Updating the README to more things which had been discussed or thought
    in the past before linking these other FLOSS project to the README and
    get them up-to-date with our current work.

 docs/README.md | 194 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 192 insertions(+), 2 deletions(-)
---
diff --git a/docs/README.md b/docs/README.md
index 14a97ab..4321e6c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -31,6 +31,7 @@ them and to be able to load them.
 For instance our extension `org.gimp.legacy.brushes` could have this
 structure:
 
+```
  org.gimp.legacy.brushes.gex:
    org.gimp.legacy.brushes/
      org.gimp.legacy.brushes.metainfo.xml
@@ -39,6 +40,7 @@ structure:
        otherbrush.gbr
        funnybrush.gih
        …
+```
 
 ### AppStream metadata
 #### Mandatory fields
@@ -84,7 +86,7 @@ which got removed in GIMP 3.0.
 
 The requires tag could be:
 
-```
+```xml
 <requires>
   <id version="2.10.2" compare="ge">org.gimp.GIMP</id>
   <id version="3.0" compare="lt">org.gimp.GIMP</id>
@@ -96,7 +98,7 @@ extension. Say your extension also depends on another. When we install
 it, we'd want the system to pull this dependency (of course it would not
 be done silently and would require approval):
 
-```
+```xml
 <requires>
   <id version="1.0" compare="ge">org.example.other_extension</id>
   <id version="2.10.2" compare="ge">org.gimp.GIMP</id>
@@ -104,6 +106,22 @@ be done silently and would require approval):
 </requires>
 ```
 
+Finally a major requirement type would be OS requirements for extensions
+which can only be run on specific platforms, or on specific versions of
+platforms. For instance, a Linux-only plug-in could be advertized this
+way:
+
+```xml
+<requires>
+  <kernel version="4.14" compare="ge">Linux</kernel>
+</requires>
+```
+
+This would work the same for Windows, macOS or various BSD kernels. We'd
+just have to come up with the right standard to name and number them
+uniquely (using the internal release of API versionning not the marketing
+names of commercial OSes in particular).
+
 #### Examples
 ##### A brush extension
 
@@ -191,6 +209,28 @@ check if updates of the extensions are available).
 </component>
 ```
 
+#### Library Software
+
+One of the nice advantage of AppStream is that it is an extensively used
+standard to describe software, which has been widely used by
+distributions to display and search for software to install (e.g. GNOME
+Software or KDE Discover). So it's nice and widespread. It also means
+that there are already a few libs reading such files.
+
+In GIMP, we use [appstream-glib](https://github.com/hughsie/appstream-glib)
+(used to not work on Windows, but I [Jehan] patched it so that it now
+works fine on all major platforms supported by GIMP). Note that all GIMP
+2.99.x development versions are already bundled with some support of the
+`.gex` format and use this lib, which is a good trial by fire.
+
+There is also a more generic [appstream](https://github.com/ximion/appstream)
+library which has several API (including another GObject one and a Qt5
+one). I don't know its current multi-platform support (back in 2018, it
+used to also not build/work on Windows, and it turns out I also have
+patches to make it work, but I forgot to contribute them as I got
+diverted into appstream-glib instead; not sure if they still apply or
+are even needed nowadays).
+
 ## Support in GIMP
 ### Repositories
 
@@ -205,6 +245,71 @@ extensions.
 Of course some layers of security would be needed (certificates,
 checksums, signed packages…).
 
+The repository format is also based on AppStream, in particular the
+"Collection Metadata" part of the format:
+https://www.freedesktop.org/software/appstream/docs/chap-CollectionData.html
+
+The extension download path can be generated from the extension ID and
+the version as advertized in the collection.
+
+### Why a single file?
+
+There is all the talk about having an "API" so software could "query"
+the extension server, make searches and whatnot. It's all very fancy and
+much more "fashionable" than old-style repository-data-in-one-file
+scheme. Why I went with the simple and single file download logics is:
+
+* Allows for extension browsing offline: maybe because the person has
+  slow or limited connection, on the move without ability to connect, or
+  any other reason (or even when the extension server itself is
+  temporarily down), you might want to browse the available extensions
+  (even if a bit outdated) without constantly querying the server.
+* Simpler server code: while it pushes the logics of searching for
+  extensions on the client side, it also allows much simpler service
+  side logics. And in particular we can even have a mostly static
+  server, which means easier maintenance and safer (see below the
+  section about `Static Code` on the server when possible).
+* Much faster and distributed search logics: instead of always asking
+  the server to do searches for you through a web API and wait for a
+  response, all the data is already present on your hard disk as a
+  single file. Searching through it should be pretty instant.
+
+This "repository info as a single file" logics has also been tried and
+proved for decades as this is how work most repository systems for
+GNU/Linux distributions (RPM, Deb, etc.).
+
+### TODO: signing
+
+There is obviously an aspect which will need to be taken care of: the
+repository files should be signed, as well as individual packages to
+avoid various types of data tampering (man-in-the-middle or other).
+
+This has not been specified yet, but should likely be done similarly to
+how various GNU/Linux distributions have been doing.
+
+### Updating the repository data
+
+Depending on how software download the repository file, it might not be
+the best idea to simply switch the XML file with a new file. If we look
+at a RPM repository for instance, the main entry point is always a very
+short `repomd.xml` which simply lists the current file with detailed
+package data.
+
+This allows to not just get rid suddenly of a slightly outdated version
+of the repository snapshot, especially while someone is looking at it.
+So the process would be to have our own equivalent of `repomd.xml`,
+which contains the name of the current repository file and its checksum.
+
+A sane process to update the repository file would be:
+
+* Add the updated repository listing named for instance
+  `<some-sha-checksum>-extensions.xml.xz`
+* Update the `repomd.xml` (or equivalent file) to point to the new
+  listing.
+* Finally remove the old listing (note that this third step can even be
+  done a bit later, allowing for some types of partial downloads in
+  steps to not fail).
+
 #### Example
 
 Our repository containing only the 2 extensions above will serve the
@@ -291,6 +396,31 @@ should notify the user and propose to update even when not looking at
 the dedicated GUI.
 
 ## Web infrastructure
+### Static Code (when possible)
+
+Something we learned with years of doing Free Software is that
+contributor time is not infinite, we cannot (and don't want to) ask
+people to fix things on a timely manner a Sunday evening, and so on. So
+we must be extra-careful and have simpler web code. This is even truer
+as making website is not our thing. We do a desktop software and want to
+have to touch the website as rarely as possible.
+And one of the best way to be careful and safe is to have mostly static
+code, which just allows nearly no attack surface (code injection or the
+like). This is why gimp.org and many other Free Software websites are
+static.
+
+Now here it might seem weird because for the extension website, we need
+creators to be able to upload their new extension update, then to
+generate new pages from these. But I am thinking this can be done in a
+slightly asynchronous way then we could have fully static pages for
+extensions, with only a minimum of dynamic code (extension upload only
+possibly).
+
+As for comment or notation, if we ever want this (we might), Pat David
+from pixls.us told us we could make use of their infrastructure.
+Therefore we may be able to have mostly static pages which comments
+handled by pixls.us infra.
+
 ### User point-of-view
 
 Though extensions can be searched within GIMP itself, it should also be
@@ -345,3 +475,63 @@ any reason. It might be interesting to create a "curator" role and have
 some people in the community promoted to such role, giving them some
 power to recommend extensions to a wide audience (unless we want
 automatic curation only, based on number of downloads for instance).
+
+### Security and code review of third-party code
+
+One of the extension type would be obviously plug-ins. This is the most
+critical part of the system, especially as GIMP doesn't have yet any
+type of sandbox for its plug-ins.
+
+Therefore just being middle-men for random developers of untrusted code
+is dangerous, if not irresponsible. On a first (simpler) version, we
+should probably:
+
+* Only allow non-compiled plug-ins, whose code can therefore be
+  inspected.
+* Not make plug-in extensions automatically available to people (unlike
+  data-type extensions when they are deemed safe). They have to go at
+  least through a first set of review by community reviewers.
+  Optionnally we may make the plug-ins available before review, but with
+  clear warning "**This has not been reviewed yet**".
+* Even after a reviewer's validation, the platform needs a way for
+  people to easily check the code and to warn us if they spot a flaw
+  (malevolent or by mistake) in an extension which makes it potentially
+  dangerous.
+* Some specific people or team well known to the community, with their
+  own well-trusted security workflow, could obtain some exception right,
+  allowing them to upload their own compiled binaries. I am speaking of
+  teams for instance like G'MIC, developed for many years by well known
+  Free Software developers, within a public research institute and
+  university (accountable and reliable).
+
+Ideally we would have the infrastructure to allow people to upload their
+code (or we would have control of their repository, see `Future future…`
+section below) and our servers could just build their plug-ins for each
+and every supported platform (Linux, Windows, macOS and other UNIXes).
+But this is definitely not a point where we are currently and we should
+not plan this at such early state.
+
+### Future future…
+
+Something I didn't want to add in early docs because I didn't want
+people to get excited about it too soon, especially as we have been
+speaking about it in meetings already years ago (and everyone was only
+speaking about it, as though it was the main point. It's not): in a
+possible future, we might want to provide source hosting for extension
+creators. It could take the shape of a self-hosted Gitlab where
+extension creators could upload their brushes, themes, plug-in code or
+whatnot, provide CI and format checking, and so on. And one could
+publish a new version of one's extension by just tagging it (hence
+updating the repository and so on, taking description from the
+metadata).
+
+This is not a new idea, I remember Wordpress was already doing this like
+at least 15 years ago (back then, with subversion, hosted by Wordpress
+itself; and you could publish a new version of your Wordpress plug-in by
+just tagging your subversion tree; I have no idea how this evolved as I
+have not developed Wordpress plug-ins lately).
+
+But this implies a whole new can of worm. See again the `Static Code`
+section as to why we want to avoid huge maintenance burden for now
+(maybe some day, if we have a lot of contributors who want to maintain a
+custom Gitlab-or-other hosting, why not…).