diff options
Diffstat (limited to 'subprojects/gnome-pwa-list/README.md')
-rw-r--r-- | subprojects/gnome-pwa-list/README.md | 61 |
1 files changed, 61 insertions, 0 deletions
diff --git a/subprojects/gnome-pwa-list/README.md b/subprojects/gnome-pwa-list/README.md new file mode 100644 index 0000000..b365319 --- /dev/null +++ b/subprojects/gnome-pwa-list/README.md @@ -0,0 +1,61 @@ +# GNOME PWA list + +This repository is a place to maintain a list of Progressive Web Apps that are +suitable for inclusion with GNOME Software. The goals of this initiative are: + +1. To facilitate the discovery of useful apps by pre-populating a list of web + apps in GNOME Software +2. To enable users to take advantage of the powerful features of PWAs, such as + offline functionality and desktop integration +3. To make the GNOME platform competitive with other platforms which already + make PWAs first-class citizens + +There is more context available in the discussion on [this issue](https://gitlab.gnome.org/GNOME/gnome-software/-/issues/1575). + +## Criteria for inclusion + +To be eligible for inclusion, PWAs must: + +- either be released under an open source license (see below) or appear in the + popular apps category [here](https://www.findpwa.com/list/top-apps) or [here](https://appsco.pe/toplist) +- be served over HTTPS +- include a [web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) with an + icon, name, and a `display` value of `fullscreen`, `standalone`, or + `minimal-ui`. The app having an Install button in Chrome means the app meets + and exceeds these criteria. +- be fully functional in GNOME Web +- not duplicate a native (non-Electron) app available for GNOME + +## Process for adding to the list + +1. Determine that the app meets all the criteria above. +2. Gather the information for each of the columns listed below. +2. If the license is [FSF-approved or OSI-approved](https://spdx.org/licenses/), + the app will go in `gnome-pwa-list-foss.csv`, otherwise `gnome-pwa-list-proprietary.csv`. +4. Add a new line in the format "URL,license,categories,content-rating,adaptive,custom-summary" to + either CSV file as appropriate. +5. Re-build the AppStream xml; see below. +6. Open a merge request [here](https://gitlab.gnome.org/mwleeds/gnome-pwa-list/-/merge_requests). + +| Column | Example value | Accepted values | +|---------|---------------|-----------------| +| URL | https://app.diagrams.net/ | the starting URL of the app | +| license | Apache-2.0 | the license(s) of the client side software in a format conforming to the AppStream [spec](https://www.freedesktop.org/software/appstream/docs/chap-Metadata.html#tag-project_license) | +| categories | Graphics;Office | one or more main or additional categories as defined [here](https://specifications.freedesktop.org/menu-spec/latest/apa.html) | +| content-rating | social-info=intense;social-audio=moderate | a set of key-value pairs which are OARS 1.1 attributes and values; see [here](https://hughsie.github.io/oars/generate.html). "social-info=none" is appropriate if the service does not even store IP addresses | +| adaptive | adaptive | either "adaptive" or "not-adaptive" depending on whether mobile devices are supported | +| custom-summary | "Telegram web app based on the open API" | a one-sentence summary to use instead of the one in the manifest, or an empty string | + +## Re-generating AppStream xml + +The script `pwa-metainfo-generator.py` can take the CSV files mentioned above +and generate AppStream metainfo for them, which enables software centers to +display them with rich metadata such as screenshots. + +1. Install the `requests` and `bs4` python3 modules using pip3 or your package manager +2. To regenerate the FOSS xml: `python3 pwa-metainfo-generator.py gnome-pwa-list-foss.xml` +3. To regenerate the proprietary xml: `python3 pwa-metainfo-generator.py gnome-pwa-list-proprietary.xml` +4. You can check the validity using e.g. `appstreamcli validate + gnome-pwa-list-foss.xml`. It will complain about missing descriptions but + GNOME Software handles those gracefully. + |