Regarding "potential difficulties":

• there is currently no Category that really fits for GCompris, I made a PR to add one on the dev version of the spec: https://github.com/italia/publiccode.yml/pull/88

• softwareType currently allows only a single value, while in our case we need both standalone/desktop and standalone/mobile... Issue opened here: https://github.com/italia/publiccode.yml/issues/89

About searchability, actually I think it's quite good already... Just make sure that the publiccode.yml contains at least a description section in english and one in italian for best results, and don't forget to add something in intendedAudience: scope: for the "Intended Audience" filter to work good.

Here is a step by step guide in order to add kde softwares to the italian open source software that Tim Paul and I wrote:
To be completed if needed. Then to be placed somewhere in KDE documentation were developers can read it.

Including your application in the Italian Open Source government catalog

Italian laws require every institution in the public sector to check within a catalog if an open source solution exists before considering buying an equivalent commercial product or developing a new solution.

Including your software in this catalog can be done very easily. It will give more visibility to your project and reinforce the role of open source software in the public sector.

Steps to include your software into the catalog:

• create the publiccode.yml file for your project
• make a pull request on https://github.com/italia/developers-italia-backend to include your project in the official repository

1- Create the publiccode.yml file for your project

-The specifications are stored in this repositiory: https://github.com/italia/publiccode.yml
(the master branch contains the current stable version of the spec)

-You can check the included examples.
Minimal version:

https://github.com/italia/publiccode.yml/blob/master/docs/en/example/publiccode.minimal.yml

Full version:

https://github.com/italia/publiccode.yml/blob/master/docs/en/example/publiccode.yml

Make sure to include at least all the fields included in the minimal version example.

You can also take a look at the publiccode.yml in GCompris repository:

https://invent.kde.org/education/gcompris/-/blob/master/publiccode.yml

1.3- Make the description attractive
Use as many screeshots as needed to make your description attractive. You can also include videos. You should think of the catalog as an app store and make your page appealing. This requires a good description of what your software is doing and relevant screenshots.

When you are done, you can double-check that your file is correct with one of those validators:

https://github.com/italia/publiccode-parser-go
https://github.com/italia/publiccode-validator

Finally, add the file at the root of your git repository.

Referencing your software in the catalog:

1- fork the following project https://github.com/italia/developers-italia-backend
2- add the link of your git repository in the file thirdparty.yml
(You can take a look at this commit as an example: https://github.com/italia/developers-italia-backend/commit/d315ca9657e9ba1ab203cdded0a088b774f5d83c " )
3- make a pull request

Brainstorm list propositions:

Taken from KDE for windows page:
They are also the one that come direct to my mind when thinking kde apps,

Okular
Kate
Filelight
Elisa
KStars
LabPlot
DigiKam
Kate & KWrite
KDevelop
Krita

I have difficulties to make any priority, except maybe for Krita :)

One that is interesting but maybe not so useful for administration, but maybe for high schools to teach accounting:

KMymoney

One I never used but is very interesting

Marble Virtual Globe, could be used in school

I never used these once:

Umbrello UML Modeller
RKWard
KEXI
Kile

As new italian citizen, I can give a hand for this project.

I have begun with Okular, Merge Request will be submited soon (today). It's a little fastidious to do, especially when you know nothing of the project. So I have used .desktop file and Okular site as information source, may be that can be automated (appstream ?), at least for the minimal version.

In T14079#249703, @yuri wrote:

As new italian citizen, I can give a hand for this project.

I have begun with Okular, Merge Request will be submited soon (today). It's a little fastidious to do, especially when you know nothing of the project. So I have used .desktop file and Okular site as information source, may be that can be automated (appstream ?), at least for the minimal version.

If needed and someone provides me an example, I could look into making apps.kde.org generate these files for us :)

If needed and someone provides me an example, I could look into making apps.kde.org generate these files for us :)

That would be amazing @ognarb .

@ognarb It sound great.

For minimal version, this is an sample file provided by https://github.com/italia/publiccode.yml with my annotations :

ubliccodeYmlVersion: "0.2"       

name: Medusa # <== Name of the app
url: "https://example.com/italia/medusa.git"    #<== URL of the git repository
softwareVersion: "stable"    # Optional
releaseDate: "2017-04-15"  # <== Last stable release date
platforms:
  - web     # <== Enumeration : web, windows, mac, linux, ios, android.

categories:
  - financial-reporting  # <== Enumeration : https://docs.italia.it/italia/developers-italia/publiccodeyml/it/master/categories-list.html#categories-list  

developmentStatus: stable  # <== Enumeration : concept, development, beta, stable, obsolete

softwareType: "standalone/desktop"   # <== almost all KDE software are mainly desktop app.

description:
  en:   # <== It will be nice to provide also the italian translation as the software is intented to be published into italian catalog
    localisedName: medusa   # Optional
    genericName: Text Editor
    shortDescription: >
          A rather short description which  # <==150 characters max
          is probably useless
    longDescription: >
          Very long description of this software, also split
          on multiple rows. You should note what the software
          is and why one should need it. We can potentially
          have many pages of text here.
    features:
       - Just one feature  # <== Free list

legal:
  license: AGPL-3.0-or-later

maintenance:
  type: "community"

  contacts:
    - name: Francesco Rossi

localisation:
  localisationReady: yes
  availableLanguages:
    - en

source : https://github.com/italia/publiccode.yml/blob/master/docs/it/example/publiccode.minimal.yml

I have validated the document and made the Merge Request for Okular with a more completed version.

https://invent.kde.org/graphics/okular/-/merge_requests/367

Nota bene : The short description can't be more than 150 characters.

Note, apparently the screenshots need to be fetched from the source repository (see https://github.com/italia/developers-italia-backend/issues/212 ).

In T14079#249713, @timotheegiet wrote:

Note, apparently the screenshots need to be fetched from the source repository (see https://github.com/italia/developers-italia-backend/issues/212 ).

Uhm, I'm not sure how that can be easily solved. On the one hand, we can't really start coping the images in repositories after moving them to the centralized repository linked to the CDN for good reason.
On the other hand, they can't just allow the images to be retrieved from the same domain, as it doesn't work for github & co.

In T14079#249713, @timotheegiet wrote:

Note, apparently the screenshots need to be fetched from the source repository (see https://github.com/italia/developers-italia-backend/issues/212 ).

My bad ! I update the MR to remove the screenshot from the manifest.

As you can see, my Merge Request was commented by the maintainers, theirs concerns are :

• the scope available is limitative
• they don't want to have theirs name or email published into public code catalogue
• they want it automated :)

I'm also new at KDE, and honestly I don't figure out what next steps can be....

Hi,
Here is a step by step guide to submit software to the italian catalog.
We did not make it public as gcompris page is still not able to be rendered peoperly. The screenshots are not to be seen in the page.
We are waiting for feedback from the catalog maintainer to see what happens.

Including your application in the Italian Open Source government catalog

Italian laws require every institution in the public sector to check within a catalog if an open source solution exists before considering buying an equivalent commercial product or developing a new solution.

Including your software in this catalog can be done very easily. It will give more visibility to your project and reinforce the role of open source software in the public sector.

Steps to include your software into the catalog:

• create the publiccode.yml file for your project
• make a pull request on https://github.com/italia/developers-italia-backend to include your project in the official repository

1- Create the publiccode.yml file for your project

-The specifications are stored in this repositiory: https://github.com/italia/publiccode.yml
(the master branch contains the current stable version of the spec)

-You can check the included examples.
Minimal version:

https://github.com/italia/publiccode.yml/blob/master/docs/en/example/publiccode.minimal.yml

Full version:

https://github.com/italia/publiccode.yml/blob/master/docs/en/example/publiccode.yml

Make sure to include at least all the fields included in the minimal version example.

You can also take a look at the publiccode.yml in GCompris repository:

https://invent.kde.org/education/gcompris/-/blob/master/publiccode.yml

1.3- Make the description attractive
Use as many screeshots as needed to make your description attractive. You can also include videos. You should think of the catalog as an app store and make your page appealing. This requires a good description of what your software is doing and relevant screenshots.

Images must be located within the invent.kde.org domain.
For GCompris a first attempt to add screenshots failed, running validators gave the following results:

docker run -i italia/publiccode-parser-go https://invent.kde.org/education/gcompris/-/raw/master/publiccode.yml
validation ko:
description/en/screenshots: Absolute URL (https://gcompris.net/screenshots_qt/large/root.png) is outside the repository (https://invent.kde.org/education/gcompris/-/raw/master/)
description/it/screenshots: Absolute URL (https://gcompris.net/screenshots_qt/large/root.png) is outside the repository (https://invent.kde.org/education/gcompris/-/raw/master/)

When you are done, a good step is to double-check that your file is correct with one of those validators:

https://github.com/italia/publiccode-parser-go
https://github.com/italia/publiccode-validator

Finally, add the file at the root of your git repository.

Referencing your software in the catalog:

1- fork the following project https://github.com/italia/developers-italia-backend
2- add the link of your git repository in the file thirdparty.yml
(You can take a look at this commit as an example: https://github.com/italia/developers-italia-backend/commit/d315ca9657e9ba1ab203cdded0a088b774f5d83c " )
3- make a pull request

In T14079#249846, @yuri wrote:

As you can see, my Merge Request was commented by the maintainers, theirs concerns are :

• the scope available is limitative
• they don't want to have theirs name or email published into public code catalogue
• they want it automated :)
  
  I'm also new at KDE, and honestly I don't figure out what next steps can be....

Hi Yuri,
Could we simply not replace the name by Okular maintainers something like:

maintenance:

type: community
contacts:
  - name: okular maintainers
    email: support@okular.net

if okular has a support email obviously.

This is something you can ask to the catalog maintainer.

In T14079#249704, @ognarb wrote:

In T14079#249703, @yuri wrote:

As new italian citizen, I can give a hand for this project.

I have begun with Okular, Merge Request will be submited soon (today). It's a little fastidious to do, especially when you know nothing of the project. So I have used .desktop file and Okular site as information source, may be that can be automated (appstream ?), at least for the minimal version.

If needed and someone provides me an example, I could look into making apps.kde.org generate these files for us :)

There is already an online page to generate publiccode.yml:
https://publiccode-editor.developers.italia.it/

In T14079#249885, @echarruau wrote:

In T14079#249846, @yuri wrote:

As you can see, my Merge Request was commented by the maintainers, theirs concerns are :

• the scope available is limitative
• they don't want to have theirs name or email published into public code catalogue
• they want it automated :)
  
  I'm also new at KDE, and honestly I don't figure out what next steps can be....

Hi Yuri,
Could we simply not replace the name by Okular maintainers something like:

maintenance:

type: community
contacts:
  - name: okular maintainers
    email: support@okular.net

if okular has a support email obviously.

This is something you can ask to the catalog maintainer.

I doubt all projects have a "support" list. Most of the big ones on kde.org have a development mailing list, though.

In T14079#249886, @echarruau wrote:

In T14079#249704, @ognarb wrote:

In T14079#249703, @yuri wrote:

As new italian citizen, I can give a hand for this project.

I have begun with Okular, Merge Request will be submited soon (today). It's a little fastidious to do, especially when you know nothing of the project. So I have used .desktop file and Okular site as information source, may be that can be automated (appstream ?), at least for the minimal version.

If needed and someone provides me an example, I could look into making apps.kde.org generate these files for us :)

There is already an online page to generate publiccode.yml:
https://publiccode-editor.developers.italia.it/

That page is not useful here. The point is that most (if not all) of the required information are available already in the metainfo/appdata files, which we use also as a source of truth for several applications, including the generation of apps.kde.org.
It would be pointless to duplicate them again. "Generate" here means "have a script which generates the publiccode.yml file from the existing information, and a policy to update it periodically when the information it uses are updated".

In T14079#249883, @echarruau wrote:

Images must be located within the invent.kde.org domain.
For GCompris a first attempt to add screenshots failed, running validators gave the following results:

docker run -i italia/publiccode-parser-go https://invent.kde.org/education/gcompris/-/raw/master/publiccode.yml
validation ko:
description/en/screenshots: Absolute URL (https://gcompris.net/screenshots_qt/large/root.png) is outside the repository (https://invent.kde.org/education/gcompris/-/raw/master/)
description/it/screenshots: Absolute URL (https://gcompris.net/screenshots_qt/large/root.png) is outside the repository (https://invent.kde.org/education/gcompris/-/raw/master/)

This is a big limitation: we shouldn't add images to invent.kde.org after spending so much time to move them in a centralized place, which is also used to populate the CDN.
Maybe it could be possible to add an alias on the invent.kde.org which points to the screenshot directory of cdn.kde.org - but that's a question for the sysadmins.

docker run -i italia/publiccode-parser-go https://invent.kde.org/education/gcompris/-/raw/master/publiccode.yml
validation ko:
description/en/screenshots: Absolute URL (https://gcompris.net/screenshots_qt/large/root.png) is outside the repository (https://invent.kde.org/education/gcompris/-/raw/master/)
description/it/screenshots: Absolute URL (https://gcompris.net/screenshots_qt/large/root.png) is outside the repository (https://invent.kde.org/education/gcompris/-/raw/master/)

We corrected this mistake :
https://invent.kde.org/education/gcompris/-/blob/master/publiccode.yml
We are now pointing to invent.kde.org. Therefore I do not understand why if fails.

@ltoscano the catalog does not embed the pictures from other resources (which would be problematic with CORS).

I might have given you a wrong pointer on Element. What is needed is the relative path in the git repo, so for example, this version would not work:

logo: https://invent.kde.org/education/gcompris/-/raw/master/images/sc-apps-gcompris-qt.svg

while this is the correct syntax:

logo: images/sc-apps-gcompris-qt.svg

you can find a good example here: https://gitlab.com/comune-di-ala/comunweb/-/blob/master/publiccode.yml

I have made the necessary changes to the publiccode.yml file and committed them to master. I did not validate them yet but they should be picked up tonight when the crawler rebuilds the catalog

To answer a few more points....

In T14079#249704, @ognarb wrote:

If needed and someone provides me an example, I could look into making apps.kde.org generate these files for us :)

That would be freaking awesome! 🙌

In T14079#249885, @echarruau wrote:

Hi Yuri,
Could we simply not replace the name by Okular maintainers something like:

maintenance:

type: community
contacts:
  - name: okular maintainers
    email: support@okular.net

That would kind of be against the specification; it is not enforced as of now, but it wouldn't be a good precedent. I'd like to avoid it if at all possible. Can't we just list one or more of the current official maintainers? These names tend to be in the "About" page of the application, and we could use the main mailing list as contact point.

In T14079#249900, @ruphy wrote:

That would kind of be against the specification; it is not enforced as of now, but it wouldn't be a good precedent. I'd like to avoid it if at all possible. Can't we just list one or more of the current official maintainers? These names tend to be in the "About" page of the application, and we could use the main mailing list as contact point.

If only the e-mail is a blocker, we can think of adding an exception for community-based projects. The rationale behind the rule was to avoid a sales or catchall address that sometimes companies provide but which is not helpful (we are interested to have a contact who can handle technical content).

My suggestion is thus to add the mailing list and we can discuss how to add an exception in the PublicCode forum.

Hmm so having image from the git repo instead of from our cdn is a bit of a problem for us. We generally recommend developers to not link directly to images or videos in gitlab from their blog or websites because we were bitten in the past by web traffic that slowed down our entire phabricator instance.

@ognarb the image will not be linked by the repository, that would break CORS settings. As I wrote above, the image will only be referenced as a relative path starting from the repository root, whoever will provide a catalog will host the images independently.

I will autocorrect myself, this is how it should work, and that's how the spec was designed (mentioned also on: T14079#249898).
Our current implementation seems to have taken the lazy way and just try to link to the git repo (which would fail in other occasions). So while this is definitely a bug we should correct, but I stand by my earlier point: it won't link directly to the git repo

One project is now working. The images needed in the description are for the moment in the git repo.
GCompris entry:
https://developers.italia.it/en/software/education-gcompris-8b38a5