diff options
Diffstat (limited to 'doc/vendor-customisation.md')
| -rw-r--r-- | doc/vendor-customisation.md | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/doc/vendor-customisation.md b/doc/vendor-customisation.md new file mode 100644 index 0000000..8866910 --- /dev/null +++ b/doc/vendor-customisation.md @@ -0,0 +1,214 @@ +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. + +Upgrade background image +------------------------ + +The background image which is shown when a new OS upgrade is available is +customisable in several ways. It’s displayed by the `GsUpgradeBanner` widget, +and shown on the updates page. + +If your distribution has a specific GNOME Software plugin providing its upgrade +information, that plugin can provide CSS for rendering the background. See the +`fedora-pkgdb-collections` plugin for an example of this. + +Otherwise, the background image is looked up from several well-known locations, +in order: + * `${DATADIR}/gnome-software/backgrounds/${os_id}-${version}.png` + * `${DATADIR}/gnome-software/backgrounds/${os_id}.png` + +`${DATADIR}` is the configured data directory (typically `/usr/share`). +`${os_id}` is the `ID=` value from `/etc/os-release`, and `${version}` is the +version string being upgraded to. + +Featured apps and Editor’s Choice +--------------------------------- + +There are several ways to promote and highlight specific applications in GNOME +Software. On the overview page, there’s a carousel of featured applications +(`featured_carousel`), and an “Editor’s Choice” section (`box_curated`). Both of +them highlight curated sets of applications. The same is true on each category +page: a carousel (`top_carousel`) and an “Editor’s Choice” section +(`featured_flow_box`) are present. + +Both pages also have a “New & Updated” section (`box_recent` or +`recently_updated_flow_box`) presented below “Editor’s Choice”. The applications +listed in the new and updated section are not curated: they are chosen as the +applications which have had a recent release, according to the +`component/releases/release[@timestamp]` attribute in their metainfo. +Technically these are the results of a `GsPlugin.list_apps_async()` query with +`GsAppQuery:released-since` set. + +Applications are included in any of the curated sets through having special +metadata in their metainfo. The required metadata is different for the different +sections: + * Carousel on the overview page: Applications are included if they have + `component/custom/value[@key='GnomeSoftware::FeatureTile]` or + `component/custom/value[@key='GnomeSoftware::FeatureTile-css]` set in their + metainfo. They are also required to have a high-resolution icon, and the set + of applications shown in the carousel is randomised and limited to (for + example) 5. Technically these are the results of a + `GsPlugin.list_apps_async()` query with `GsAppQuery:is-featured` set. + * “Editor’s Choice” on the overview page: Applications are included if they + have `component/kudos/kudo[text()='GnomeSoftware::popular']` set in their + metainfo. Technically these are the results of a `GsPlugin.list_apps_async()` + query with `GsAppQuery:is-curated` set. + * Carousel on the category page: Applications are included if they are in the + `Featured` subcategory of the displayed category. They are also required to + have a high-resolution icon, and the set of applications shown in the carousel + is randomised and limited to (for example) 5. + * “Editor’s Choice” on the category page: Applications are included if they + meet the requirements for being in the carousel, but weren’t chosen as part + of the randomisation process. + +Example: +```xml +<?xml version="1.0" encoding="UTF-8"?> +<components> + <component merge="append"> + <!-- The ID must always be present to allow merging --> + <id>org.gnome.Podcasts</id> + + <!-- Make the app a candidate for inclusion in the carousel on the + overview page (if it has a hi-res icon). --> + <custom> + <value key="GnomeSoftware::FeatureTile">True</value> + </custom> + + <!-- Include the app in the “Editor’s Choice” section on the overview page. --> + <kudos> + <kudo>GnomeSoftware::popular</kudo> + </kudos> + + <!-- Make the app a candidate for inclusion in the carousel or + “Editor’s Choice” section on category pages (if it has a hi-res icon). --> + <categories> + <!-- Note that, due to a bug (https://gitlab.gnome.org/GNOME/gnome-software/-/issues/1649), + currently all the other categories for the app must also be listed + here, as well as the additional ‘Featured’ category. --> + <category>AudioVideo</category> + <category>Player</category> + <!-- This category has been added: --> + <category>Featured</category> + </categories> + </component> + <!-- more components --> +</components> +``` + +There are several ways to modify the metainfo for applications so that they are +highlighted as required, all of which involve providing an additional appstream +file which sets the additional metainfo for those applications. + +The main approach is to ship an additional distro-specific appstream file in +`${DATADIR}/swcatalog/xml`, providing and updating it via normal distribution +channels. For example, by packaging it in its own package which is updated +regularly. + +For distributions which can’t do regular updates of individual files – such as +image-based distributions – GNOME Software can download distro-specific +appstream files from the internet. List them in the `external-appstream-urls` +GSetting in `/org/gnome/software`, typically via a distribution-provided +GSettings override. Each URL must be HTTPS, and must point to a valid appstream +file. GNOME Software must be configured with `-Dexternal_appstream=true` for +this to work. + +GNOME Software will periodically check and download any updates to these +files, and will cache them locally. Ensure the `If-Modified-Since` HTTP header +functions correctly on your server, or GNOME Software’s caching will be +ineffective. + +The `external-appstream-urls` mechanism may change in future. + +GNOME Software ships a default list of featured applications, chosen to match +the [GNOME Circle](https://circle.gnome.org/). See +`data/assets/org.gnome.Software.Featured.xml` for this list, and for an example +of the metainfo XML needed to feature or highlight applications. See +`data/assets/org.gnome.Software.Curated.xml` for a default hard-coded list of +curated high quality applications, which is displayed in the “Editor’s Choice” +section of the overview page. + +Pass `-Ddefault_featured_apps=false` when configuring GNOME Software to disable +the default list of featured applications. Pass `-Dhardcoded_curated=false` to +disable the default list of “Editor’s Choice” applications. + +Deployment Featured Apps +------------------------ + +Deployments can feature their own applications, which will be shown in the Explore +page in its own section. To have the section shown, two files need to be provided. +The number of deployment-featured apps is limited in the UI, and if not enough +deployment-featured apps are found, then the section will not be shown at all. + +The first file is `org.gnome.Software.DeploymentFeatured.xml`, which works similarly +to `org.gnome.Software.Featured.xml` and should be saved beside it in an appstream +directory. It sets the `GnomeSoftware::DeploymentFeatured` key on apps which should +be featured for this distribution or deployment. The value of this key is a string +containing the deployment name as an identifier. + +The second file is `deployment-featured.ini`, which contains a human-readable title and +the selector for the section. The title is a localized key, and is used to set the heading +for the section on the Explore page. The selector defines which apps should be picked. +It is a semicolon-separated list of `GnomeSoftware::DeploymentFeatured` key values, thus +the deployment can feature apps from zero or more vendors. + +The `deployment-featured.ini` file should be saved in one of the `sysconfdir`, system +config dirs or system data dirs. They are checked, in that order, for existence of +the `gnome-software/deployment-featured.ini` file. The first directory containing +it will be used. The relevant file names are `/etc/xdg/gnome-software/deployment-featured.ini`, +`/usr/local/share/gnome-software/deployment-featured.ini` and +`/usr/share/gnome-software/deployment-featured.ini`. + +Any changes to these files, including adding or removing them, will only be noticed +when gnome-software is restarted. + +Example files can be found in the `contrib/` directory. |