[gimp-extensions-web] docs: add some documentation to explain the base concepts.

[Jehan <jehanp src gnome org>]

commit f83921e47e3b114e436b4e55ad9ca8fc43d8b312
Author: Jehan <jehan girinstud io>
Date:   Tue Jun 4 18:40:56 2019 +0200

    docs: add some documentation to explain the base concepts.

 docs/README | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 186 insertions(+)
---
diff --git a/docs/README b/docs/README
new file mode 100644
index 0000000..11db1af
--- /dev/null
+++ b/docs/README
@@ -0,0 +1,186 @@
+# Infrastructure for GIMP extensions
+
+This document contains some basic information about the whole extension
+system of GIMP. It is likely to evolve a lot as we are still working on
+it.
+
+## Extension format
+
+A GIMP extension has an **unique** identifier in reverse-DNS scheme. For
+instance, say the GIMP core team decided to remove some old brushes from
+default GIMP and publish these as an extension (so that anyone would
+still be able to install these old brushes, while keeping core GIMP of
+highest quality). This extension could be called for instance
+`org.gimp.legacy.brushes`. If *ZeMarmot* project wanted to publish some
+brushes to paint trees, an acceptable name for the extension could be
+`net.zemarmot.film.tree_brushes`.
+
+The extension itself is a compressed file (currently `zip` format, but
+this is not set in stone yet), which makes GIMP extensions easy to share
+and distribute as single-files, as the new `.gex` format.
+
+It contains at its root a single directory named as the extension ID.
+Inside this directory, a metadata file is present, named as the
+extension ID appended with `.metainfo.xml`. This file uses the
+[AppStream format](https://www.freedesktop.org/software/appstream/docs/).
+
+Finally it could have any random data files. These additional files will
+have to be declared inside the metadata in order for GIMP to know about
+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
+     brushes/
+       somebrush.gbr
+       otherbrush.gbr
+       funnybrush.gih
+       …
+
+### AppStream metadata
+#### Mandatory fields
+
+A GIMP extension metadata is mandatorily a [component of type
+"addon"](https://www.freedesktop.org/software/appstream/docs/sect-Metadata-Addon.html).
+
+Therefore it must have these fields:
+
+* id
+* extends: with the value `org.gimp.GIMP`
+* name
+* summary
+* metadata_license
+
+Additionally our repository requires some additional fields because the
+goal is for people to understand what they are going to install.
+Extensions with just a name and a few words are not very useful. You'd
+also want:
+
+* project_license
+* description
+* screenshots: at least one image
+* releases: tagging at least your releases with a version and a date
+
+#### Recommended fields
+
+For completeness, we would recommend to add some `<url/>` tags if
+relevant, in particular "homepage" and "bugtracker" so that people are
+able to get more information and raise any issues your extension may
+have.
+
+On our side, our infrastructure should be able to display the "donation"
+url if available to help extension creators.
+
+#### Requirements
+
+If the creator knows that one's extension won't work properly for older
+or newer version of GIMP, we would recommend to set the `<requires>`
+tag. For instance, say you are developing a plug-in, using new APIs
+which appeared in 2.10.2. On the other hand, it uses a deprecated API
+which got removed in GIMP 3.0.
+
+The requires tag could be:
+
+```
+<requires>
+  <id version="2.10.2" compare="ge">org.gimp.GIMP</id>
+  <id version="3.0" compare="lt">org.gimp.GIMP</id>
+</requires>
+```
+
+Now another great feature we'd want to support is dependency to another
+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):
+
+```
+<requires>
+  <id version="1.0" compare="ge">org.example.other_extension</id>
+  <id version="2.10.2" compare="ge">org.gimp.GIMP</id>
+  <id version="3.0" compare="lt">org.gimp.GIMP</id>
+</requires>
+```
+
+## Support in GIMP
+### Repositories
+
+A default repository maintained by the GIMP core team will be set by
+default. There is probably no reason to forbid third-party repositories
+so these could be supported (added through GIMP Preferences).
+
+GIMP will simply download a static file from an extension repository,
+which will contain the metadata for all available extensions.
+
+Of course some layers of security would be needed (certificates,
+checksums, signed packages…).
+
+### Dedicated GUI
+
+The GUI would allow searching (through extension names, descriptions,
+etc.), viewing extension details, installing (by downloading the actual
+file), uninstalling, updating extensions, etc.
+
+### Notifications
+
+If an already installed extension is available in a newer version, GIMP
+should notify the user and propose to update even when not looking at
+the dedicated GUI.
+
+## Web infrastructure
+### User point-of-view
+
+Though extensions can be searched within GIMP itself, it should also be
+possible to view the list of extensions in a web browser, and detailed
+extension pages, without accounts.
+
+Note that it should be possible also to comment (and maybe note?)
+extensions. These possibilities may require accounts though.
+
+Finally anyone should be able to flag any extension deemed dangerous
+(whether on purpose or because of unexpected issues), with some
+description explaining the issue.
+
+### Creator point-of-view
+
+An extension creator would need an account to be able to create a new
+extension page then publish new versions of an extension. Publishing a
+new version means simply uploading a `.gex` file following the format
+described above. The system would have to make sure that the format
+requirements are respected, that the version number got bumped, and so
+on.
+
+It should also check that the contents corresponds to the advertized
+data.
+
+Finally it should flag potentially dangerous data for review before
+actually publishing it. I.e. in particular plug-ins and scripts would
+require review before being distributed.
+
+Binary plug-ins should be forbidden except for specific creators well
+known and trusted. This last requirement can only be lifted in a future
+where our infrastructure will be able to compile these binary plug-ins
+from source.
+
+Note: the idea has been floating around to be able to track a source
+repository and automatically generate new releases upon tagging. This
+may be a possible future path for helping extension maintainership.
+
+### Reviewer point-of-view
+
+This whole system can only work if we gather a trusted community from
+which we can promote "reviewers". These reviewers would have the role to
+accept or refuse extensions needing reviews, as well as make decisions
+on explicitly flagged extensions.
+
+Detailed review rules would have to be decided.
+
+### Curator point-of-view
+
+It may be interesting to be able to put forward specific extensions, for
+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).