[gnome-software: 1/2] doc: Add documentation file for app developers

[Milan Crha <mcrha src gnome org>]

commit 8b5650199e60e520799203e6597c0288b7074b5a
Author: Philip Withnall <pwithnall endlessos org>
Date:   Thu Feb 10 14:59:09 2022 +0000

    doc: Add documentation file for app developers
    
    This will cover information about GNOME Software relevant to app
    developers, such as how they can test what their app will look like in
    GNOME Software.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Helps: !1164

 doc/app-developers.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
---
diff --git a/doc/app-developers.md b/doc/app-developers.md
new file mode 100644
index 000000000..dad5da701
--- /dev/null
+++ b/doc/app-developers.md
@@ -0,0 +1,69 @@
+Tools in GNOME Software for application developers
+==================================================
+
+GNOME Software is often where users will first come into contact with an
+application which they might later install, so the impression the user gets of
+that application is important. Application developers want to see how their
+application will appear in GNOME Software, and to have some control over it.
+
+GNOME Software provides some tools to help with this.
+
+If there is a supported tool which is not in this document, please
+[submit a merge request](https://gitlab.gnome.org/GNOME/gnome-software/-/merge_requests/new)
+to document it.
+
+Metainfo/Appstream
+------------------
+
+The information about an application comes from its metainfo (or, as it was
+previously known: appdata) file. Metainfo files for multiple applications are
+concatenated into ‘appstream’ files. Almost all of the customisation which GNOME
+Software provides for applications comes from information in metainfo or
+appstream files.
+
+So the first thing to check for your application is that its metainfo file is
+complete and valid. See the
+[metainfo file specification](https://www.freedesktop.org/software/appstream/docs/).
+
+To validate your metainfo file, run
+```
+appstreamcli validate /path/to/app.metainfo.xml
+```
+
+You can add this as a unit test to your application by adding the following to
+the appropriate `meson.build` in your application:
+```
+metainfo_file = files('com.example.MyApp.metainfo.xml')
+appstreamcli = find_program('appstreamcli', required: false)
+if appstreamcli.found()
+  test (
+    'Validate metainfo file',
+    appstreamcli,
+    args: ['validate', '--no-net', metainfo_file],
+  )
+endif
+```
+
+Context tiles
+-------------
+
+The context tiles which are shown on an application’s details page in GNOME
+Software are derived from the application’s metainfo.
+
+There’s more detailed information about them, and the information they are built
+from, [on the GNOME Software wiki](https://gitlab.gnome.org/GNOME/gnome-software/-/wikis/Software-metadata).
+
+Previewing the details page for an application
+----------------------------------------------
+
+GNOME Software allows previewing how an application will appear, by loading its
+metainfo file directly. This allows previewing in-progress changes to an
+application without publishing it to a repository.
+
+Do this with the `--show-metainfo` argument:
+```
+gnome-software --show-metainfo=/path/to/app.metainfo.xml,icon=/path/to/icon.png
+```
+
+This will show the application in the details page of GNOME Software, and will
+also display it in the featured carousel on the overview page.