1.1.1. Chiave publiccodeYmlVersion¶

• Tipo: stringa
• Presenza: obbligatoria
• Esempio: "0.1"

Questa chiave specifica la versione alla quale il presente publiccode.yml aderisce, per una questione di compatibilità diretta.

1.1.2. Chiave name¶

• Tipo: stringa
• Presenza: obbligatoria
• Esempio: “Medusa”

Questa chiave contiene il nome del software. Contiene il nome (abbreviato) pubblico del prodotto, che può essere tradotto nella sezione specifica chiamata localisation. Dovrebbe essere il nome con il quale la maggior parte delle persone si riferisce al suddetto software. Nel caso in cui il software abbia sia un nome in “codice” interno che uno commerciale, è preferibile usare il nome commerciale.

1.1.3. Chiave applicationSuite¶

• Tipo: stringa
• Presenza: opzionale
• Esempio: “MegaProductivitySuite”

Questa chiave contiene il nome della “suite” alla quale il software appartiene.

1.1.4. Chiave url¶

• Tipo: stringa (URL)
• Presenza: obbligatoria
• Esempio: "https://example.com/italia/medusa.git"

Un identificatore unico per questo software. Questa stringa deve essere una URL che punta al repository di codice sorgente (git, svn, …) nel quale il software è pubblicato. Se il repository è disponibile sotto diversi protocolli, preferire URL HTTP/HTTPS che non richiedono l’autenticazione.

I fork creati con lo scopo di contribuire upstream non devono modificare questo file; questo aiuta i software che fanno il parsing di publiccode.yml a saltare immediatamente i fork tecnici. Al contrario, un fork completo che sarà manutenuto in modo separato rispetto al software originale, dovrebbe modificare questa linea per essere trattato come una variante distinta.

Vedi Fork e varianti per una descrizione completa del significato di variante software e di come gestire i fork sia lato parser che lato autore.

1.1.5. Chiave landingURL¶

• Tipo: stringa (URL)
• Presenza: opzionale
• Esempio: "https://example.com/italia/medusa"

Se la chiave url non porta ad una pagina leggibile da un umano, ma serve solo ad indirizzare un client di source control verso il codice sorgente, con questa chiave viene introdotta l’opzione di specificare la landing page. Questa pagina, idealmente, è il punto di arrivo dell’utente quando seleziona un pulsante chiamato, ad esempio, “Vai al codice sorgente dell’applicazione”. Nel caso in cui il prodotto preveda un installer grafico automatico, questa URL può puntare alla pagina contenente un riferimento al codice sorgente ma che offra anche la possibilità di scaricare tale installer.

1.1.6. Chiave isBasedOn¶

• Tipo: stringa o array di stringhe
• Presenza: opzionale
• Esempio: "https://github.com/italia/otello.git"

Nel caso in cui questo software sia una variante o un fork di un altro software, che opzionalmente può contenere un file publiccode.yml, questa chiave conterrà la url di uno o più progetti originali.

L’esistenza di questa chiave identifica il fork come una variante (vedi Fork e varianti), discendente dal repository specificato.

1.1.7. Chiave softwareVersion¶

• Tipo: stringa
• Presenza: opzionale
• Esempio: "1.0", "dev"

Questa chiave contiene il numero dell’ultima versione stabile del software. Il numero di versione è una stringa che non è pensata per essere interpretata dal parser ma solamente visualizzata; i parser non devono assumere l’utilizzo del semantic versioning o altri specifici formati di versionamento.

Questa chiave può essere omessa nel caso in cui il software sia in una fase iniziale di sviluppo e non sia stato ancora rilasciato.

1.1.8. Chiave releaseDate¶

• Tipo: stringa (data)
• Presenza: obbligatoria
• Esempio: "2017-04-15"

Questa chiave contiene la data di ultimo rilascio del software. Questa data è obbligatoria se il software è stato rilasciato almeno una volta e dunque esiste un numero di versione.

1.1.9. Chiave logo¶

• Tipo: stringa (percorso verso il file)
• Presenza: opzionale
• Formati accettabili: SVG, SVGZ, PNG
• Esempio: "img/logo.svg"

Questa chiave indica il logo del software. Il valore può essere il percorso relativo al file a partire dalla root del repository, oppure una URL assoluta che punta al logo in versione raw. In entrambi i casi, il file deve risiedere all’interno del medesimo repository che contiene il publiccode.yml. Il logo dovrebbe essere in formato vettoriale; i formati raster sono solo accettabili come fallback. In questo caso, dovrebbero essere PNG trasparenti, con una larghezza minima di 1000px.

1.1.10. Chiave monochromeLogo¶

• Tipo: stringa (percorso verso il file)
• Presenza: opzionale
• Formati accettabili: SVG, SVGZ, PNG
• Esempio: "img/logo-mono.svg"

Questa chiave indica il logo monocromatico (nero) del software. Il valore può essere il percorso relativo al file a partire dalla root del repository, oppure una URL assoluta che punta al logo in versione raw. In entrambi i casi, il file deve risiedere all’interno del medesimo repository che contiene il publiccode.yml. Il logo dovrebbe essere in formato vettoriale; i formati raster sono solo accettabili come fallback. In questo caso, dovrebbero essere PNG trasparenti, con una larghezza minima di 1000px.

1.1.11. Chiave inputTypes¶

• Tipo: array di stringhe
• Presenza: opzionale
• Valori: vedi RFC 6838
• Esempio: "text/plain"

Una lista di Media Types (MIME Types), come specificato dal RFC 6838, che possono essere gestiti in input dall’applicazione.

Nel caso in cui il software non supporti alcun input, è possibile saltare questo campo o usare application/x.empty.

1.1.12. Chiave outputTypes¶

• Tipo: array di stringhe
• Presenza: opzionale
• Valori: vedi RFC 6838
• Esempio: "text/plain"

Una lista di Media Types (MIME Types), come specificato dal RFC 6838, che possono essere gestiti in output dall’applicazione.

Nel caso in cui il software non supporti alcun output, è possibile saltare questo campo o usare application/x.empty.

1.1.13. Chiave platforms¶

• Tipo: stringhe o array di stringhe
• Presenza: obbligatoria
• Valori: web, windows, mac, linux, ios, android. Valori leggibili da un umano al di fuori di questa lista sono permessi.
• Esempio: web

Questa chiave specifica su quale piattaforma funziona il software. È pensata per descrivere le piattaforme che l’utente userà per accedere ed utilizzare il software, piuttosto che la piattaforma sul quale il software gira.

Se possibile, usare i valori predefiniti. Se il software gira su una piattaforma per la quale un valore predefinito non è disponibile, un diverso valore può essere usato.

1.1.14. Chiave categories¶

• Tipo: array di stringhe
• Presenza: obbligatoria
• Valori accettabili: vedi Lista delle categorie di software

Una lista di parole che possono essere usate per descrivere il software e possono aiutare a costruire il catalogo di software open.

Il vocabolario controllato Lista delle categorie di software presenta la lista dei valori accettabili.

1.1.15. Chiave usedBy¶

• Tipo: array di stringhe
• Presenza: opzionale

Una lista di nome di prominenti Pubbliche Amministrazioni (che serviranno come “testimonial”) che il maintainer riconosce come utilizzatori attuali di questo software.

I parser sono incoraggiati ad accrescere questa lista anche con altre informazioni che riescono ad ottenere in modo indipendente; ad esempio, il fork di un software, di proprietà di un’amministrazione, può essere usato come un segnale di uso del software.

1.1.16. Chiave roadmap¶

• Tipo: stringa
• Presenza: opzionale

Un link ad una roadmap pubblica del software.

1.1.17. Chiave developmentStatus¶

• Tipo: stringa
• Presenza: obbligatoria
• Valori permessi: concept, development, beta, stable, obsolete

Le chiavi sono:

• concept - Il software è solo un “concept”. Non è stato sviluppato codice e il repository potrebbe semplicemente essere un placeholder.
• development - Qualche sforzo è stato fatto in direzione dello sviluppo del software ma il codice non è pronto per l’utenza finale, nemmeno in una versione preliminare (beta o alpha) per essere testato dall’utenza.
• beta - Il software è in fase di testing (alpha o beta). In questo stage, il software potrebbe aver o non aver ancora avuto una release pubblica preliminare.
• stable - Il software ha già avuto una prima release pubblica ed è pronto per essere usato in un contesto di produzione.
• obsolete - Il software non è più manutenuto o aggiornato. Tutto il codice sorgente è archiviato e tenuto per ragioni di storico.

1.1.18. Chiave softwareType¶

• Tipo: stringa
• Presenza: obbligatoria
• Valori permessi: "standalone/mobile", "standalone/iot", "standalone/desktop", "standalone/web", "standalone/backend", "standalone/other", "addon", "library", "configurationFiles"

Le chiavi sono:

• standalone/mobile - Il software è un pacchetto self-contained, standalone. Il software è un’applicazione nativa per dispositivi mobile.
• standalone/iot - Il software è adatto ad essere utilizzato nel contesto Internet of Things.
• standalone/desktop - Il software è tipicamente installato e utilizzato su un sistema operativo desktop.
• standalone/web - Il software rappresenta un applicativo fruibile attraverso il web.
• standalone/backend - Il software è un applicativo backend.
• standalone/other - Il software ha una natura diversa rispetto a quanto specificato alle chiavi precedenti.
• softwareAddon - Il software è un addon, come ad esempio un plugin o un tema, per un software più complesso (e.g., un CMS o una suite per ufficio).
• library - Il software contiene una libreria o una SDK che facilita la creazione di nuovi prodotti a sviluppatori di terze parti.
• configurationFiles - Il software non contiene script eseguibili ma una serie di file di configurazione. Questi potrebbero documentare come ottenere un certo tipo di deployment. I suddetti file potrebbero avere la forma di semplici file di configurazione, script bash, playbook ansible, Dockerfile, o altri set di istruzioni.

1.1.19. Sezione intendedAudience¶

1.1.20. Sezione description¶

Questa sezione contiene una descrizione generale del software. I parser possono usare questa sezione ad esempio per creare una pagina web che descriva il software.

Nota bene: siccome tutte le stringhe contenute in questa sezione sono visibili all’utente e scritte in un linguaggio specifico, è necessario specificare il linguaggio con il quale si sta modificando il testo. Per farlo è necessario creare una sezione dedicata alla lingua seguendo le specifiche IETF BCP 47. Si ricorda che il primary language subtag non può essere omesso, come specificato nel BCP 47.

Un esempio per l’italiano:

description:
  it:
    shortDescription: ...
    longDescription: ...

Nelle parti successive del documento, tutte le chiavi sono assunte essere all’interno di una sezione con il nome della lingua (annoteremo questo con [lang]).

Nota bene: è obbligatorio avere almeno una lingua in questa sezione. Tutte le altre lingue sono opzionali.

1.1.21. Sezione legal¶

1.1.22. Sezione maintenance¶

Questa sezione fornisce informazioni sullo stato di manutenzione del software, utile per valutare se il software è attivamente sviluppato o meno.

1.1.23. Sezione localisation¶

Questa sezione fornisce una panoramica sulle funzionalità di localizzazione del software.

1.1.24. Sezione dependsOn¶

Questa sezione fornisce una panoramica delle dipendenze a livello di sistema necessarie per installare ed utilizzare il software.

Nota bene: non elencare le dipendenze a livello di codice sorgente (ad es., librerie software usate), e focalizza solo su dipendenze di sistema e/o a runtime che devono essere installate e manutenute separatamente. Ad esempio, un database è un buon esempio di questo tipo di dipendenza.

1.2.1. Dependency¶

Una dependency è un oggetto complesso. Le proprietà sono le seguenti:

• name - obbligatoria - Il nome della dipendenza (e.g. MySQL, NFC Reader);
• versionMin - la prima versione compatibile;
• versionMax - l’ultima versione compatibile;
• version - l’unica versione major con la quale il software è compatibile. Si assume la compatibilità con tutte le patch e i bugfix che saranno applicati successivamente a questa versione;
• opzionale - se la dipendenza è opzionale o obbligatoria.

1.2.2. Versioning complesso¶

E’ ovviamente possibile utilizzare le varie chiavi per specificare una matrice di compatibilità complessa.

Ex. 1

- name: PostgreSQL
  version: "3.2"
  opzionale: yes

Questo snippet segnala una dipendenza opzionale verso PostgreSQL, nell’esattezza la sua versione 3.2.

Ex. 2

- name: MySQL
  versionMin: "1.1"
  versionMax: "1.3"

Questo snippet segnala una dipendenza obbligatoria verso MySQL, permettendo ogni versione tra la 1.1 e la 1.3.

1.2.3. Contatto¶

Un Contatto è un oggetto con le seguenti proprietà:

• name - obbligatoria - Questa chiave contiene il nome completo di uno dei contatti tecnici. Deve essere una persona reale; NON popolare questa chiave con informazioni di contatto generiche, dipartimenti dell’azienda, associazioni, etc.
• email - Questa chiave contiene l’indirizzo email del contatto tecnico. Deve essere un indirizzo email per il contatto diretto con il tecnico; NON popolare questa chiave con mailing-list o punti di contatto generico tipo “info@acme.inc”. Questo indirizzo email non deve essere offuscato. Per migliorare la resistenza contro la raccolta di indirizzi email, usare \x64 per sostituire @, siccome questo è permesso dalle specifiche YAML.
• phone - Numero telefonico (con prefisso internazionale). Questa chiave deve essere una stringa.
• affiliation - Questa chiave contiene informazioni esplicite sui contatti tecnici. Nel caso esistano diversi maintainer, questa chiave può essere usata per creare relazioni tra diversi contatti tecnici e entità di manutenzione. Ad esempio, può contenere il nome di un’azienda, il nome di un’associazione, etc.

1.2.4. Contractor¶

Un Contractor è un oggetto con le seguenti proprietà:

• name - obbligatoria - Il nome del contractor, sia esso un’azienda o una persona fisica.
• until - obbligatoria - Questa è una data (YYYY-MM-DD). Questa chiave deve contenere una data alla quale la manutenzione finirà. Nel caso di manutenzione gestita dalla community, questo valore non deve essere maggiore di 2 anni nel futuro, e quindi deve essere regolarmente aggiornata man mano che la community continua a lavorare al progetto.
• email - Questa chiave contiene l’indirizzo email del contatto tecnico. Deve essere un indirizzo email per il contatto diretto con il tecnico; NON popolare questa chiave con mailing-list o punti di contatto generico tipo “info@acme.inc”. Questo indirizzo email non deve essere offuscato. Per migliorare la resistenza contro la raccolta di indirizzi email, usare \x64 per sostituire @, siccome questo è permesso dalle specifiche YAML.
• website - Questa chiave punta al sito del maintainer. Può puntare al principale sito istituzionale, o ad una pagina o sito più specifica.

1.2.5. Data¶

Tutte le date in publiccode.yml devono aderire al formato “YYYY-MM-DD” che è uno dei formati permessi da ISO8601. Nota bene: questo è l’unico formato permesso, quindi non sono consentiti gli altri formati previsti da ISO8601.

1.2.6. Codifica¶

La codifica di publiccode.yml DEVE essere UTF-8.