From 53fcdafe11d2d98fa56e0c5cc67ebe9d085bbd3c Mon Sep 17 00:00:00 2001 From: Muhammad Alfi Syahrin Date: Mon, 1 Jul 2024 13:51:38 +0700 Subject: [PATCH 1/3] Add appstream metainfo docs Resolves https://github.com/getsolus/help-center-docs/issues/551 --- docs/packaging/appstream-metainfo.md | 51 ++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/packaging/appstream-metainfo.md diff --git a/docs/packaging/appstream-metainfo.md b/docs/packaging/appstream-metainfo.md new file mode 100644 index 000000000..6f56d5c49 --- /dev/null +++ b/docs/packaging/appstream-metainfo.md @@ -0,0 +1,51 @@ +--- +title: Appstream Metainfo +summary: The purpose and format of Appstream Metainfo +--- + +# AppStream Metainfo + +:::important + +AppStream metainfo is required for the inclusion of graphical application to Solus repository. + +::: + +AppStream allows upstream projects to define metadata about the components they provide using small XML files, metainfo files, which get installed into locations on the client system and are used by distributors to enhance their metadata. + +AppStream metainfo become a requirement for Solus because new software centers such as GNOME software and KDE Siscover rely on it to know which applications are available in repository. Typically AppStream metainfo is shipped bundled with graphical application itself, but sometimes upstream doesn't do so. Packagers are required to add AppStream metainfo themselves when that happen. + +## Adding appstream metainfo to an existing package + +There are a few scenarios that Packagers might encounter: + +|No | Scenario |Solution | +| -------- | --------------------------------- | -----------| +| 1 | An application already provides appstream metainfo| Nothing to do| +|2| An application contains appstream metainfo in the source package but we do not install it | Install the appstream metainfo to `/usr/share/metainfo`. _Example_: [here](https://github.com/getsolus/packages/commit/0a726a53454e7c8a6b0e66de69d59bcc66f0fc19 )| +|3| An application doesn't contain appstream metainfo in the source package but it exists on Flathub | Borrow and tweak the appstream metainfo from the Flathub repo. Encourage upstream to add it to their source. _Example_: [here](https://github.com/getsolus/packages/commit/da2f65b93f412da43d1db9edbcb08bb90517a0eb)| +|4| An application doesn't provide appstream metainfo and it doesn't exist on flathub| Write the appstream data, submit it to upstream. _Example_: [here](https://github.com/getsolus/packages/commit/414219d8b2ceeabe85178d3a467f81b9131016f4)| +| 5 |Appstream metainfo is provided but generation of it is failing| See [here](https://github.com/getsolus/solus-appstream-data#debugging-failures). _Example_: [here](https://github.com/getsolus/packages/commit/583b7c742caf50e2f66a70e9b62e9b91566c03f5).| + + +AppStream metadata is to be placed in the `/usr/share/metainfo/` directory and must be placed in the package which should be installed in order to get the software described by the respective metadata. This means that you might need to move the *.metainfo.xml or *.appdata.xml to the right (meta)package. + +In case your AppStream metadata is describing a desktop-application (you can tell by the XML root-node having a type="desktop-application" or type="desktop" attribute), the .appdata.xml file must be placed in the same package as the .desktop file already is, which (as above) must be the package containing the application itself. + +## Testing appstream data + +- Clone the package repo + +- Build it or eopkg fetch pkgname + +- Run `sudo eopkg it appstream-glib`, `appstream-builder --packages-dir=. --include-failed -v` + +- Look in the `example-failed.xml.gz` file to see if the appstream generation failed + +- Look in the `example.xml.gz` file to see if the appstream generation succeeded. + +- Install the package and run `appstream-util validate /usr/share/metainfo/pkgname.xml` + +## Other Info + +Generally speaking, a package must provide one appstream metainfo file, an icon as well as an .desktop file to succeed. However, there are exceptions to this. If an application provides more than one appstream metainfo file then the package must be subpackaged to generation of all the appstream metainfo files to succeed. \ No newline at end of file From 818ca2fde6fdd067d168b371508c5de6a16d50a4 Mon Sep 17 00:00:00 2001 From: David Harder Date: Fri, 4 Oct 2024 12:33:41 -0500 Subject: [PATCH 2/3] Run Prettier, Add to allowed-words --- .cspell-allowed-words.txt | 2 ++ docs/user/software/development/postgresql.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.cspell-allowed-words.txt b/.cspell-allowed-words.txt index 210a7a375..11128dece 100644 --- a/.cspell-allowed-words.txt +++ b/.cspell-allowed-words.txt @@ -104,6 +104,7 @@ ferryd filesharing firstpost flarum +flathub flatpak flicky flto @@ -220,6 +221,7 @@ maintainership markus mendeleydesktop metacity +metainfo mojang moneydance mountpoint diff --git a/docs/user/software/development/postgresql.md b/docs/user/software/development/postgresql.md index aa3278b83..2c0b3de38 100644 --- a/docs/user/software/development/postgresql.md +++ b/docs/user/software/development/postgresql.md @@ -39,7 +39,7 @@ Because PostgreSQL is included as a single package, the only way to perform a ma ```bash sudo eopkg it https://cdn.getsol.us/repo/shannon/p/postgresql/postgresql-16.4-51-1-x86_64.eopkg \ - https://cdn.getsol.us/repo/shannon/p/postgresql/postgresql-libpq-16.4-51-1-x86_64.eopkg + https://cdn.getsol.us/repo/shannon/p/postgresql/postgresql-libpq-16.4-51-1-x86_64.eopkg ``` 2. (Re)start PostgreSQL: From 5b2aa0e74e52c492d2f8b138c9abec219e3aa3bf Mon Sep 17 00:00:00 2001 From: Muhammad Alfi Syahrin Date: Wed, 6 Nov 2024 14:27:32 +0700 Subject: [PATCH 3/3] Fix typo and wording --- docs/packaging/appstream-metainfo.md | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/docs/packaging/appstream-metainfo.md b/docs/packaging/appstream-metainfo.md index 6f56d5c49..7ccbcfa0b 100644 --- a/docs/packaging/appstream-metainfo.md +++ b/docs/packaging/appstream-metainfo.md @@ -7,13 +7,13 @@ summary: The purpose and format of Appstream Metainfo :::important -AppStream metainfo is required for the inclusion of graphical application to Solus repository. +AppStream metainfo is required for all graphical application in Solus repository. ::: -AppStream allows upstream projects to define metadata about the components they provide using small XML files, metainfo files, which get installed into locations on the client system and are used by distributors to enhance their metadata. +AppStream allows upstream projects to define metadata about the components they provide using small XML files, metainfo files, which get installed into locations on the client system and are used by distributors to enhance their metadata. -AppStream metainfo become a requirement for Solus because new software centers such as GNOME software and KDE Siscover rely on it to know which applications are available in repository. Typically AppStream metainfo is shipped bundled with graphical application itself, but sometimes upstream doesn't do so. Packagers are required to add AppStream metainfo themselves when that happen. +AppStream metainfo become a requirement for all graphical application in Solus repository because software centers such as GNOME software and KDE Discover rely on it to display applications that are available in repository. AppStream metainfo should be shipped by the upstream project, bundled in with its source, but sometimes upstream projects don't do so. In which case, packagers are required to add AppStream metainfo themselves. ## Adding appstream metainfo to an existing package @@ -21,18 +21,18 @@ There are a few scenarios that Packagers might encounter: |No | Scenario |Solution | | -------- | --------------------------------- | -----------| -| 1 | An application already provides appstream metainfo| Nothing to do| -|2| An application contains appstream metainfo in the source package but we do not install it | Install the appstream metainfo to `/usr/share/metainfo`. _Example_: [here](https://github.com/getsolus/packages/commit/0a726a53454e7c8a6b0e66de69d59bcc66f0fc19 )| -|3| An application doesn't contain appstream metainfo in the source package but it exists on Flathub | Borrow and tweak the appstream metainfo from the Flathub repo. Encourage upstream to add it to their source. _Example_: [here](https://github.com/getsolus/packages/commit/da2f65b93f412da43d1db9edbcb08bb90517a0eb)| -|4| An application doesn't provide appstream metainfo and it doesn't exist on flathub| Write the appstream data, submit it to upstream. _Example_: [here](https://github.com/getsolus/packages/commit/414219d8b2ceeabe85178d3a467f81b9131016f4)| -| 5 |Appstream metainfo is provided but generation of it is failing| See [here](https://github.com/getsolus/solus-appstream-data#debugging-failures). _Example_: [here](https://github.com/getsolus/packages/commit/583b7c742caf50e2f66a70e9b62e9b91566c03f5).| +| 1 | An application already provides appstream metainfo| Nothing to do| +|2| An application contains appstream metainfo in the source package but we do not install it | Install the appstream metainfo to `/usr/share/metainfo`. _Example_: [here](https://github.com/getsolus/packages/commit/0a726a53454e7c8a6b0e66de69d59bcc66f0fc19 )| +|3| An application doesn't contain appstream metainfo in the source package but it exists on Flathub | Borrow and tweak the appstream metainfo from the Flathub repo. Encourage upstream project to add it to their source. _Example_: [here](https://github.com/getsolus/packages/commit/da2f65b93f412da43d1db9edbcb08bb90517a0eb)| +|4| An application doesn't provide appstream metainfo and it doesn't exist on flathub| Write the appstream metadata, submit it to upstream project. _Example_: [here](https://github.com/getsolus/packages/commit/414219d8b2ceeabe85178d3a467f81b9131016f4)| +| 5 |Appstream metainfo is provided but generation of it is failing| See [here](https://github.com/getsolus/solus-appstream-data#debugging-failures). _Example_: [here](https://github.com/getsolus/packages/commit/583b7c742caf50e2f66a70e9b62e9b91566c03f5).| -AppStream metadata is to be placed in the `/usr/share/metainfo/` directory and must be placed in the package which should be installed in order to get the software described by the respective metadata. This means that you might need to move the *.metainfo.xml or *.appdata.xml to the right (meta)package. +AppStream metainfo is to be installed in the `/usr/share/metainfo/` directory. It must be placed in the package which should be installed in order to get the software described by the respective metadata. This means that you might need to move the *.metainfo.xml or *.appdata.xml to the right (sub)package. -In case your AppStream metadata is describing a desktop-application (you can tell by the XML root-node having a type="desktop-application" or type="desktop" attribute), the .appdata.xml file must be placed in the same package as the .desktop file already is, which (as above) must be the package containing the application itself. +In case your AppStream metainfo is describing a desktop-application (you can tell by the XML root-node having a type="desktop-application" or type="desktop" attribute), the .appdata.xml file must be placed in the same package as the .desktop file already is, which (as above) must be the package containing the application itself. -## Testing appstream data +## Testing appstream metainfo - Clone the package repo @@ -44,8 +44,6 @@ In case your AppStream metadata is describing a desktop-application (you can tel - Look in the `example.xml.gz` file to see if the appstream generation succeeded. -- Install the package and run `appstream-util validate /usr/share/metainfo/pkgname.xml` - ## Other Info -Generally speaking, a package must provide one appstream metainfo file, an icon as well as an .desktop file to succeed. However, there are exceptions to this. If an application provides more than one appstream metainfo file then the package must be subpackaged to generation of all the appstream metainfo files to succeed. \ No newline at end of file +A package must provide one appstream metainfo file, an icon file and a .desktop file for AppStream generation to succeed. However, there are exceptions to this. If an application provides more than one AppStream metainfo file then the package must be subpackaged for generation of all the appstream metainfo files to succeed.