menu di navigazione del network

[LG-SW] Allegato B: Guida alla pubblicazione di software Open Source

Collegamento:
https://lg-acquisizione-e-riuso-software-per-la-pa.readthedocs.io/it/latest/attachments/allegato-b-guida-alla-pubblicazione-open-source-di-software-realizzato-per-la-pa.html

Contenuto:
Allegato B: Guida alla pubblicazione di software Open Source

  1. Premessa
  2. Individuazione della piattaforma di code hosting
  3. Scelta della licenza
  4. Attribuzione della licenza ed individuazione della titolarità
  5. Individuazione dei materiali da rilasciare
  6. Rilascio del codice e organizzazione del repository
  7. File README
  8. Documentazione
  9. Tempi di rilascio
  10. Sicurezza
  11. Registrazione del repository su Developers Italia

Al pararagrafo 5.3.3 si dice che la licenza è definita dall’Amministrazione.
Poi si dice che “Il Fornitore è tenuto (MUST) a garantire la compatibilità di tale licenza con quelle di eventuali componenti riutilizzati od incorporati, con o senza modifiche, per i quali non si detiene il copyright”, ma non si dice invece come si deve comportare per le eventuali librerie già sviluppate in precedenza dallo stesso fornitore che vengono riutilizzate all’interno del nuovo prodotto. Non è automatico infatti che l’Amministrazione acquisisca la titolarità anche di queste componenti, ma occorre fare attenzione che l’utilizzo di tali componenti da parte del fornitore non pregiudichi la possibilità di riuso del sistema nel suo complesso.
Secondo me andrebbe esplicitato il comportamento corretto da parte del fornitore.

Par. .5.2

  • posto che l’elenco relativo ai possibili “code hosting” è nutrito, si suggerisce di valutare l’eliminazione di quelli a pagamento.

Par. 5,2,2

  • si conserva quale perplessità circa la possibilità che sia il fornitore ad esprimere una scelta circa il repertorio: la PA dovrà meglio indicare il proprio repertorio o, in alternativa, indicare quello della soluzione terza, in caso in cui lo scenario sia l’evoluzione di una soluzione preesistente (dando in questo caso priorità all’iterazione diretta con la community originale).

Par. 5,3,3

Par. 5.5

  • sarebbe opportuno aggiungere dell’altra tipologia di documentazione, sia funzionale alla scelta, sia funzionale all’uso, come ad esempio: Manuale Utente, Architettura di Deploy, Matrici di Compatibilità SW, risultati dei test di vulnerabilità, risultati stress test, etc.

In merito alla documentazione da produrre come corredo al rilascio, nel paragrafo 5.5 andrebbero aggiunti, come già richiesto, manuali utente, manuali di amministrazione e configurazione, documentazione grafica dei database e documenti di analisi.
Questa documentazione dovrebbe essere corredata da metadati descrittivi utilizzabili ai fini di conservazione (ad esempio con metadati PREMIS) e per creare le opportune dipendenze per la loro comprensione nel tempo (intellectual entities di PREMIS).

Nel paragrafo 5.8, si richiede documentazione di tipo tecnico di supporto al prodotto e si cita “La documentazione in formato ODT, DOCX o PDF non è ammessa”. Credo che andrebbe chiarito se questo ambito si riferisca unicamente alla documentazione tecnica da rilasciare nei repository e quindi sottoposta a versionamento di riga oppure si intende applicarla anche alla documentazione tecnica come quella relativa a descrizioni dell’architettura, al disegno di database, test e così via.

Inoltre nel prosieguo del paragrafo, si richiedono formati aperti, modificabili e multipiattaforma limitatamente a " documentazione sull’utilizzo del software rivolta agli utenti finali". Si potrebbe inserire una indicazione ulteriore di allineamento sui formati previsti dall’Allegato 2 delle "Regole tecniche in materia di sistema di conservazione " (DPCM 3/12/2013) ed estendere l’indicazione a tutta la documentazione di corredo del prodotto.
Questo al fine di allinearsi a formati in grado di supportare il processo di conservazione del patrimonio informativo e conoscitivo del software e delle sue realizzazioni.

Da parte del Centro Hermes per la Trasparenza e Diritti Umani Digitali:

Facendo seguito al nostro contributo per l’Allegato-E sulla modifica di software opensource di terzi siamo a specificare e dettagliare nostro contributo.

Punto 6:

Si propone di aggiungere la seguente regola:

Il repository pubblicato dovrebbe (MAY) contenere tutta la storia delle modifiche dei “code commit” che il fornitore ha effettuato durante il processo di sviluppo, preservando lo storico dell’operato dell’attività di sviluppo, necessario e utile a tutti gli sviluppatori che vorranno contribuire per ridurre la curva di apprendimento. Nel caso il software in riuso sia basato su un software opensource di terzi, la raccomandazione di cui sopra diviene obbligatoria (MUST).

Punto 7:

Nel caso in cui il software sia basato su un opensource di terzi, è necessario aggiungere nel file README.md le seguenti informazioni:

SE il “software in riuso” è stato allineato al “software opensource di terzi” indicare:

(MUST) Tutte le modifiche necessarie alla amministrazione in riuso sono state integrate nel software opensource d’origine

SE il “software in riuso” non è stato allineato al “software opensource di terzi” indicare:
(MUST) Descrizione estesa di tutte le interazioni con il maintainer documentando i singoli sforzi di integrazione delle modifiche nel software originario:

  • Ticket/Issues aperti (con indicazione se sono ancora da integrare o integrati)
  • Discussioni da archivi di mailing list
  • Log di Chat (ove presenti archiviazioni di chat nel progetto originale)
  • Draft/design document di integrazione con il progetto per la sua estensione
  1. Tempi di rilascio

Nel caso in cui il software sia basato su un opensource di terzi, In relazione ai tempi di rilascio, il Fornitore deve prima assicurarsi di avere inviato tutte le richieste di integrazione al Maintainer del software opensource di terzi, e solo in seguito provvedere alla pubblicazione.

Scopo della regola di cui sopra è evitare il tipo “Code dump alla bersagliera” fatto dal Fornitore considerando il contributo al “software opensource di terzi” su cui si è basato marginale.

Su questo punto sono dubbioso, agli sviluppatori non serve sempre lo storico dei commit, inoltre se viene richiesto servono delle linee guida riguardo la loro struttura e contenuto. Spesso nei progetti privati questi commit hanno descrizioni incomplete o solo dei segnaposti del tipo “fix”, ma fix di cosa?
Quindi probabilmente richiedere lo storico può creare dei blocchi perché vanno revisionati tutti quanti e vedere se questo codice storico (che potrebbe avere anni) contenga cose di pubblico dominio.
Mettiamo ad esempio che prima utilizzava materiale che non può essere rilasciato sotto GPL e poi è stato corretto con materiale sotto licenza. Lo storico quindi dovrà essere ripulito.

Io per il momento mi accontenterei di avere del codice vista la situazione attuale in cui manca proprio, poi magari un domani dopo che il modo di pensare è cambiato si può forzare anche questo passaggio.

In merito al “Punto 6”

Si, ma nel caso in cui il software sia basato su un opensource di terzi, è necessario conoscere ogni singolo commit e la sua sequenza, proprio per comprendere cosa sia stato modificato senza dovere fare diff.
Inoltre, la sequenza di commit, anche se commentata con “fix”, per il developer ha comunque un significato importante perché mostra tutto il percorso di modifiche, di bug incontrati, di workaround adottati, nonché consente di comprendere le scelte stilistiche o di design che magari sono partite in un modo e sono evolute in un altro (cosa spesso non documentata, ma “leggibile” nel code commit flow).

Il problema di partecipare a progetti opensource di cui hai il “code dump alla bersagliera” come fa’ ad esempio la comunità europea, è che ti devi scaricare un mega ZIP di cui non hai la storia e non ne conosci l’evoluzione, né hai la possibilità di conoscerla (vedi: https://joinup.ec.europa.eu/news/ec-publishes-open-source-code) .

Insomma non è il “dump di codice” che ha valore a se, ma anche l’esperienza del percorso dei developers che hanno portato a quel codice, e questo è rappresentato in quota parte dai code commit, che rendono appunto più “accessibile” l’apprendimento e comprensione del codice per chi ci si approcciasse.

Si non lo metto in dubbio ma specificare il rilascio dello storico dei commit ha bisogno di una serie di regole e guide in modo tale che sia utile.
Quindi credo che applicarlo ora rallenterebbe ancora di più il rilascio di materiale :grinning:

Si, però non ho capito quale sarebbe la difficoltà di rilasciare lo storico dei commit.

Lo storico dei commit non richiede review di sorta, si tratterebbe solo prendere l’intero repository di codice, inclusivo dei commit e pubblicarlo.

Ora, posto che lo storico dei commit rappresenta un valore della conoscenza del software e che non “costa” pubblicarli, tanto vale farceli mettere.

Per fare una analogica sulla necessità di pubblicare i commit, sarebbe come obbligare la pubblicazione di una “legge fatta e finita nella versione finale” ma escludere tutto il processo di emendamenti e correzioni fatti nel processo parlamentare.

La storia che porta alla determinazione di una legge è importante quanto la legge stessa, lo stesso IMHO dicasi per il percorso che porta alla versione finale e rilasciata di un software.

Il problema non è tanto lo storico di per se ma il testo dei commit ad esempio https://github.com/italia/docs-italia-theme/commits/master
Devono essere in italiano o inglese? Devono essere più lunghi di 10 caratteri? devono essere autoesplicativi?
Ad esempio in questo repo non sono molto autoesplicativi https://github.com/italia/bootstrap-italia/commits/master

Mi riferisco a questo con storico, se io mi ritrovo con uno storico di 3 anni ad esempio i titoli devono potermi aiutare a leggere lo storico sennò non è molto utile averlo e diventa solo un qualcosa da revisionare (su cui poi istruire gli sviluppatori).