[gnome-software: 1/5] doc: Add stub document on vendor customisations

[Milan Crha <mcrha src gnome org>]

commit 186fcc48b9e59042d02cfe7e918000c74edfe525
Author: Philip Withnall <pwithnall endlessos org>
Date:   Fri Feb 4 14:40:25 2022 +0000

    doc: Add stub document on vendor customisations
    
    This will grow over time to document the different ways in which
    distributions can customise gnome-software for their distribution.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>

 doc/vendor-customisation.md | 51 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
---
diff --git a/doc/vendor-customisation.md b/doc/vendor-customisation.md
new file mode 100644
index 000000000..9529d3d6b
--- /dev/null
+++ b/doc/vendor-customisation.md
@@ -0,0 +1,51 @@
+Vendor customisation of GNOME Software
+======================================
+
+GNOME Software is in an unusual position in a distribution, as it lies at the
+interface of the GNOME project and the distribution’s packaging and release
+infrastructure. GNOME Software is the user interface which a lot of users will
+use to see updates and new releases from their distribution. Distributions
+understandably want to be able to put some of their own branding on this
+interface, both to publicise their distribution and to confer some level of
+official authority on the updates being provided.
+
+For this reason, GNOME Software has a few ways which vendors can use to
+customise its appearance.
+
+A variety of different customisations have been implemented in the past, some of
+which have been removed and others are still present. This document aims to
+document the ones which are still present and supported. This document is *not
+necessarily complete*. It will be added to over time as different customisations
+are refreshed and updated.
+
+If there is a supported customisation method which is not in this document,
+please [submit a merge request](https://gitlab.gnome.org/GNOME/gnome-software/-/merge_requests/new)
+to document it.
+
+Likewise, if your distribution would like to customise gnome-software in a way
+which isn’t currently supported, please
+[open a new issue](https://gitlab.gnome.org/GNOME/gnome-software/-/issues/new?issue%5Bmilestone_id%5D=)
+to discuss it. We don’t guarantee to implement anything, and customisations are
+limited to adding branding in specific areas.
+
+Principles
+----------
+
+The principles which guide vendor customisation features in GNOME Software are:
+ * Avoid requiring vendor specific code.
+   - Otherwise vendors have to maintain and test GNOME Software plugins, which
+     is a lot of work.
+ * Don’t use GSettings unless customisations really should be per-user.
+   - While GSettings overrides are convenient, they are designed for user
+     preferences, not packaging customisation.
+ * Don’t require downstream patching of GNOME Software, although configure-time
+   arguments are OK.
+   - Many distributions are derived from other ones and would not like to have
+     to maintain a packaging fork in order to make small customisations.
+ * Be mindful of release cadences.
+   - If customisations related to a new OS version were tied to the release
+     cycle of GNOME Software, a new GNOME Software packaging release would have
+     to be done by a distribution in advance of making their new OS release,
+     which is a burden.
+   - It’s easier to allow distributions to put customisations specific to a new
+     OS version into a separate package.