Philip Withnall
philip@tecnocode.co.uk
Will Thompson
wjt@endlessos.org
Milan Crha
mcrha@redhat.com
Come Software usa i metadati
Davide Ferracin
davide.ferracin@protonmail.com 2025

# Metadati del software

# Schermate

Software mostra delle schermate nella pagina dei dettagli di un'applicazione. Ciò include solitamente schermate di varie finestre dell'applicazione, in modo che l'utente possa comprendere rapidamente le caratteristiche, l'aspetto e le funzionalità dell'applicazione.

Quando nel file metainfo dell'applicazione è presente più di una schermata, Software mostrerà le schermate in un carosello.

Nei casi in cui il file metainfo dell'applicazione non contenga alcuna schermata, verrà visualizzata un'icona segnaposto come quella riportata di seguito con la dicitura `Nessuna schermata`:

Se si utilizza un tema di icone personalizzato, l'icona segnaposto potrebbe apparire diversa.

Man mano che l'interfaccia utente dell'applicazione si evolve, le schermate potrebbero diventare obsoleti. Pertanto, anche se Software mostra le schermate di un'applicazione, è importante verificare se esse siano aggiornate o obsolete.

Per migliorare le informazioni sulle schermate delle applicazioni:

Come aggiungere una schermata mancante dell'applicazione

# Barra contestuale dell'applicazione

La barra contestuale dell'applicazione in Software è una raccolta di riquadri nella pagina dei dettagli, che visualizzano le seguenti informazioni.

Archiviazione

Sicurezza

Supporto hardware

Classificazione per età

Questo mostra la barra di contesto di Software stessa:

I riquadri vengono mostrati nell'ordine sopra elencato (iniziando dal riquadro `Archiviazione` sulla sinistra).

Ogni riquadro è descritto dettagliatamente di seguito.

# Archiviazione

Software mostra un riquadro di archiviazione nella pagina dei dettagli di un'applicazione. Se l'applicazione non è installata, viene visualizzata la dimensione stimata dello scaricamento necessario per installarla. Se l'applicazione è già installata, viene visualizzato lo spazio di archiviazione utilizzato dall'applicazione.

Le dimensioni sono calcolate a partire dai dati forniti dal backend di Software (come flatpak o un RPM) e non sono specificate nei metadati forniti dall'applicazione. Non è possibile modificare questo riquadro modificando il file metainfo di un'applicazione. Viene elencato qui per completezza.

# Sicurezza

Software mostra un riquadro di sicurezza nella pagina dei dettagli di un'applicazione. Questo riquadro riassume le informazioni relative alla sicurezza dell'installazione e dell'esecuzione dell'applicazione, indicando se è necessario fare attenzione prima di considerarla affidabile.

Il riquadro combina le informazioni relative alle autorizzazioni richieste dall'applicazione durante l'esecuzione (ad esempio l'autorizzazione a leggere i file dell'utente) con le informazioni relative al suo sviluppo. Il software gratuito, il cui codice sorgente è pubblicamente accessibile, può rivelarsi più sicuro di quello proprietario, in quanto può essere direttamente verificato.

Quando si clicca sul riquadro appare una finestra di dialogo che elenca le diverse autorizzazioni richieste dall'applicazione, oltre ad alcune informazioni sulla sua licenza e sul suo runtime.

Per migliorare le informazioni sulla sicurezza:

Come correggere informazioni errate su sicurezza e autorizzazioni

# Supporto hardware

Software mostra un riquadro relativo al supporto hardware nella pagina dei dettagli di un'applicazione. Questo riquadro combina le informazioni sui requisiti hardware dell'applicazione e sulle capacità hardware del computer, con l'obiettivo di evidenziare eventuali incompatibilità o requisiti mancanti, oppure di indicare che l'applicazione dovrebbe funzionare correttamente senza alcuna incompatibilità.

Il codice prende in considerazione il seguente hardware. In futuro altri dispositivi potrebbero essere supportati.

Se sono presenti/necessari un touchpad, un mouse o una tastiera.

Se è necessario un gamepad

Le dimensioni dello schermo minime e consigliate alle quali l'applicazione può adattarsi

Non è possibile rilevare in modo affidabile se un gamepad è presente poiché spesso viene lasciato scollegato, non essendo necessario per il normale utilizzo del computer.

La finestra di dialogo che appare quando si fa clic sul riquadro elenca i diversi requisiti hardware dell'applicazione e indica se qualcuno di essi non è soddisfatto.

Per migliorare le informazioni sull'hardware:

Come aggiungere informazioni mancanti sull'hardware

# Classificazione per età

Software mostra un riquadro con la classificazione per età nella pagina dei dettagli di un'applicazione. Questo riquadro indica la fascia d'età per cui si considera adatta l'applicazione, in base ai diversi tipi di contenuti che essa ha dichiarato di contenere. Queste informazioni sono riassunte in un formato simile ai certificati di classificazione dei giochi o dei film di ciascun Paese.

Ad esempio, questo metterà in evidenza se un gioco contiene scene di violenza o se un'applicazione contiene pubblicità al suo interno.

La finestra di dialogo che appare quando si clicca sul riquadro elenca i diversi tipi di contenuti presenti nell'applicazione e la loro gravità.

Per migliorare le informazioni sulla classificazione per età:

Come aggiungere informazioni mancanti sulla classificazione per età

# Licenza

Software mostra un riquadro che indica se un'applicazione è software libero o se la sua licenza è proprietaria, speciale o sconosciuta. Questo riquadro include informazioni più dettagliate sulla licenza del progetto. Il riquadro elenca anche alcuni dei vantaggi del software libero. Ulteriori informazioni

A volte le informazioni sulla licenza non sono corrette per un'applicazione, e quindi un'applicazione che in realtà è software libero verrà visualizzata come “proprietaria”. Allo stesso modo, a volte le informazioni sulla licenza sono sconosciute.

Software evidenzia le licenze gratuite e open source in verde, e quelle proprietarie e speciali in giallo, come mostrato qui. Le licenze sconosciute sono evidenziate in grigio.

Per aggiungere o migliorare le informazioni sulla licenza:

Come correggere informazioni errate sulla licenza

# Collegamenti

Software mostra, nel riquadro dei collegamenti, un elenco di collegamenti alle risorse dell'applicazione. Essi sono:

| Collegamento al sito web
| Collegamento per fare una donazione
| Collegamento per contribuire alla traduzione
| Collegamento per segnalare un problema
| Collegamento per ottenere aiuto
| Collegamento per entrare in contatto

Tutti o alcuni di questi collegamenti potrebbero essere presenti, in base a quali di essi sono elencati nel file metainfo dell'applicazione.

Laddove il file metainfo dell'applicazione non contenga alcun collegamento, verrà mostrato il seguente riquadro con un punto di domanda.

Per migliorare i collegamenti:

Come aggiungere collegamenti mancanti

# Riquadro del carosello

Le applicazioni presentate da Software vengono visualizzate in un carosello nella parte superiore della finestra principale, come mostrato qui. Ogni riquadro del carosello ha un colore di sfondo che viene estratto automaticamente dall'icona dell'applicazione. A volte questo colore di sfondo non è del tutto adatto all'applicazione e deve essere specificato esplicitamente dal suo sviluppatore.

Sono i manutentori della distribuzione Linux che si usa a decidere quali applicazioni vengono presentate.

Per migliorare il riquadro del carosello:

Come impostare il colore di sfondo del riquadro del carosello

# Da dove vengono i metadati

I metadati utilizzati per specificare l'hardware richiesto da un software, l'età degli utenti ai quali è adatto e i fattori che contribuiscono alla sicurezza della sua installazione provengono tutti dal file metainfo di quel software.

Il file metainfo è un file XML. Il suo formato è dettagliato nelle specifiche AppStream.

Consultare il file metainfo per l'applicazione File di GNOME.

Il vecchio nome per metainfo è appdata.

# Cosa succede se mancano dei metadati

Se mancano alcuni metadati di un'applicazione, Software può solo ipotizzare quali potrebbero essere, quindi non sarà in grado di presentare molte informazioni nelle sue interfacce. Le ipotesi formulate da Software si basano sul fatto che la maggior parte dei software è progettata per computer desktop.

Si può aiutare a migliorare i metadati di un'applicazione!

# Come fornire le informazioni mancanti

Se si ritiene che la pagina di un'applicazione sia incompleta o contenga informazioni errate, si può contribuire in uno dei due modi seguenti:

Segnalare i metadati mancanti o incorretti nel bug tracker dell'applicazione, così che gli sviluppatori possano correggerli.

Correggere i metadati mancanti o incorretti da soli. Consultare la guida di seguito per scoprire come fare.

Per entrambi, bisogna prima trovare la pagina del progetto dell'applicazione. Il collegamento alla pagina del progetto dovrebbe essere disponibile nella pagina dell'applicazione come mostrato qui. In caso contrario, lo si dovrà cercare con una semplice ricerca su Google.

Le applicazioni sono solitamente ospitate su GitLab o GitHub. Ad esempio, le applicazioni di GNOME sono ospitate su gitlab.gnome.org.

# Come aggiungere le schermate mancanti delle applicazioni

Le informazioni sulle schermate per un'applicazione sono contenute nell'elemento `<screenshots>` all'interno dell'elemento `<component>` dell'applicazione nel suo file metainfo.

È consigliato per le applicazioni un numero di schermate tra 5 e 10. Le schermate dovrebbero idealmente essere nel formato PNG con un rapporto 16:9 e una larghezza minima di 620 pixel.

Ad esempio, queste sono le schermate per l'applicazione Software stessa:

<screenshots> <screenshot type="default"> <image>https://gitlab.gnome.org/GNOME/gnome-software/raw/HEAD/data/metainfo/ss-overview.png</image> <caption>Overview panel</caption> </screenshot> <screenshot> <image>https://gitlab.gnome.org/GNOME/gnome-software/raw/HEAD/data/metainfo/ss-details.png</image> <caption>Details panel</caption> </screenshot> </screenshots>

# Come correggere le informazioni sbagliate su sicurezza e autorizzazioni

Le informazioni relative alla sicurezza e alle autorizzazioni di un'applicazione provengono da fonti diverse a seconda di come l'applicazione è stata impacchettata. Per le applicazioni impacchettate in modo tradizionale, ad esempio in formato RPM o DEB, non sono disponibili informazioni relative alla sicurezza o alle autorizzazioni e non è possibile aggiungerle all'applicazione.

Per le applicazioni flatpak, le informazioni provengono dal manifesto flatpak dell'applicazione, che specifica quali aperture nella sandbox sono richieste all'applicazione. Ciascuna di queste aperture ha l'effetto in genere di abbassare il livello di sicurezza visualizzato dell'applicazione in Software, spostandolo da “sicuro” a “potenzialmente non sicuro” fino a “non sicuro”.

Per migliorare il livello di sicurezza di un'applicazione, la sua sandbox deve essere la più rigorosa possibile, rimuovendo le autorizzazioni sandbox dove non sono necessarie e utilizzando al loro posto, dove possibile, i portali. L'uso dei portali non riduce il livello di sicurezza di un'applicazione mostrato in Software.

Ad esempio, se l'applicazione richiede l'accesso in lettura/scrittura all'intero file system (`--filesystem=host`), ne ha effettivamente bisogno o deve solo accedere ai file in alcune posizioni specifiche? In tal caso, è possibile utilizzare il portale dei file oppure definire permessi del file system più specifici.

Se l'applicazione funziona su Wayland, e ha bisogno di X11 solo come ripiego, senza far uso di sue funzionalità specifiche, potrebbe usare `--socket=fallback-x11` anziché `--socket=x11`?

In futuro qui potrebbero essere aggiunte indicazioni relative a specifici permessi o altri formati di pacchetti.

Ulteriori approfondimenti:

# Come aggiungere informazioni mancanti sull'hardware

Le informazioni sull'hardware per un'applicazione sono contenute negli elementi `<requires>`, `<recommends>` e `<supports>` all'interno dell'elemento `<component>` del suo file metainfo.

Software è in grado di leggere gli elementi `<control>` e `<display_length>`.

Consultare questo blog post o questo blog post per leggere alcuni esempi di metadati.

# Come aggiungere informazioni mancanti sulla classificazione per età

Le informazioni sulla classificazione per età di un'applicazione sono contenute nell'elemento `<content_rating>` all'interno dell'elemento `<component>` nel suo file metainfo.

Per compilare questo elemento, le applicazioni devono utilizzare lo standard OARS 1.1. Se l'elemento `<content_rating>` non è specificato, la classificazione dei contenuti dell'applicazione è sconosciuta. Se è specificato ma è vuoto, significa che l'applicazione non ha contenuti che potrebbero essere inadatti a qualsiasi tipo di pubblico.

Per produrre informazioni sulla classificazione per età adatte a un'applicazione, usare il generatore OARS.

# Come correggere informazioni errate sulla licenza

Le informazioni sulla licenza di un'applicazione sono contenute nell'elemento `<project_license>` all'interno dell'elemento `<component>` nel suo file metainfo.

Il contenuto di questo elemento deve essere un'espressione SPDX che descrive la licenza “principale” del progetto. In genere, dovrebbe trattarsi della licenza del codice, senza includere la licenza della documentazione o dei contenuti accessori.

Se l'espressione SPDX è una licenza singola o una disgiunzione inclusiva di più licenze, tutte approvate dalla FSF o dall'OSI, l'applicazione è considerata “software libero” e il riquadro della licenza indica questo fatto. In caso contrario, è considerata “proprietaria”.

Se un'applicazione viene visualizzata come “proprietaria” quando si ritiene che non dovrebbe esserlo, è probabile che l'elemento `<project_license>` includa la licenza della documentazione per il progetto. Rimuoverlo.

Per esempio, cambiare i metadati della licenza da:

<project_license>GPL-2.0+ and CC-BY-SA-3.0</project_license>

a

<project_license>GPL-2.0+</project_license>

Ulteriori approfondimenti:

Non inserire (in generale) la licenza della documentazione negli appdata

# Come aggiungere collegamenti mancanti

I collegamenti per un'applicazione sono contenuti negli elementi `<url>` all'interno dell'elemento `<component>` nel suo file metainfo.

Aggiungere tutti i tipi di collegamento documentati nelle specifiche appstream disponibili per l'applicazione. Se non esiste una pagina adatta ad un determinato tipo di collegamento, non è necessario includerlo.

Per esempio, ecco i collegamenti alle risorse per l'applicazione Software:

<url type="bugtracker">https://gitlab.gnome.org/GNOME/gnome-software/-/issues</url> <url type="contact">https://discourse.gnome.org/tag/gnome-software</url> <url type="contribute">https://welcome.gnome.org/app/Software/</url> <url type="donation">https://www.gnome.org/donate/</url> <url type="homepage">https://apps.gnome.org/Software</url> <url type="translate">https://l10n.gnome.org/module/gnome-software/</url> <url type="vcs-browser">https://gitlab.gnome.org/GNOME/gnome-software/</url>

# Come impostare il colore di sfondo per il riquadro del carosello

Normalmente il colore di sfondo del riquadro del carosello viene estratto automaticamente dall'icona dell'applicazione. Se tale colore non è soddisfacente, tuttavia, è possibile sovrascriverlo utilizzando l'elemento `<branding/>` di appstream con i colori dichiarati (a partire dalla serie 47.x). Il vantaggio è che un numero maggiore di client può utilizzare i colori.

Ecco alcune voci di «branding»:

<branding> <color type="primary" scheme_preference="light">#ff00ff</color> <color type="primary" scheme_preference="dark">#993d3d</color> </branding>

Notare che l'attributo `scheme_preference` viene ignorato, Software sceglie autonomamente il miglior colore per il tema.

Per garantire la retrocompatibilità, rimane la possibilità di aggiungere il seguente codice XML all'elemento `<component>` del metainfo dell'applicazione:

<custom> <value key="GnomeSoftware::key-colors">[(124, 53, 77), (99, 16, 0)]</value> </custom>

ma l'elemento `<branding/>` mantiene la precedenza.

Il valore di `GnomeSoftware::key-colors` è un GVariant in formato testo con tipo `a(yyy)`, e rappresenta un insieme non ordinato di colori chiave per l'applicazione. Ciascun elemento dell'insieme è un colore in formato RGB nell'intervallo da `(0, 0, 0)` a `(255, 255, 255)`.

I colori dovrebbero essere scelti in modo che:

Siano associabili all'applicazione, corrispondendo in qualche modo, se possibile, al suo marchio.

Contrastino con il bordo dell'icona dell'applicazione, in modo che quando vengono utilizzati come sfondo dietro di essa l'icona rimanga ben distinta.

Contrastino con il colore del testo in primo piano del tema Adwaita (`#2e3436`) e con la sua variante scura (`#eeeeec`). Questo significa in generale scegliere un colore con un livello di luminosità medio.

Il contrasto può essere controllato usando l'applicazione Contrasto.

È necessario specificare almeno un colore. È possibile specificarne più di uno se un solo colore non soddisfa tutti i requisiti sopra indicati, in tal caso Software sceglierà quello più appropriato da utilizzare nel riquadro carosello. Se viene specificato un solo colore, la sua luminosità e la sua saturazione potrebbero venire modificate per migliorare il contrasto con il colore di primo piano. Se vengono specificati più colori, verrà scelto quello con il miglior contrasto con il colore di primo piano, e la sua luminosità e saturazione non verranno modificate.

# Come verificare i cambiamenti al colore di sfondo del riquadro del carosello

Modificare il file metainfo della propria applicazione, quindi lanciare Software con:

gnome-software --show-metainfo=/posizione/del/file/app.metainfo.xml,icon=/posizione/del/file/icona-applicazione.png

Verrà visualizzata la pagina dei dettagli della propria applicazione. Se si torna alla panoramica di Software, la propria applicazione sarà l'unica presente nel carosello “in primo piano”.