Le fasi di sviluppo e riuso di software¶

Nel seguito sono descritte nel dettaglio la fase di sviluppo e la fase di riuso di software evidenziando in particolare le interazioni che avvengono con il catalogo.

Diagramma esemplificativo della fase di sviluppo:

1. La PA “A” decide di sviluppare un ipotetico software “Imago” da zero e lo commissiona a uno sviluppatore (interno o tramite appalto).
2. La PA “A” acquisisce la completa titolarità di quanto sviluppato.
3. La PA “A” incarica lo sviluppatore di pubblicare il codice sorgente completo della soluzione con licenza libera, durante o al termine della lavorazione, su uno strumento di code hosting.
4. Il software viene “registrato” su Developers Italia, per acquisire visibilità nazionale e internazionale.

Diagramma esplicativo della fase di riuso:

1. La PA “B”, durante la valutazione comparativa, cerca su Developers Italia un software a riuso adatto alle proprie esigenze e trova “Imago”.
2. La PA “B” scarica liberamente il software dallo strumento di code hosting della PA “A” e lo valuta in autonomia.
3. La PA “B” incarica uno sviluppatore di personalizzare il software, installarlo, mantenerlo, e formare il proprio personale. Questo sviluppatore può essere lo stesso o un altro, ma deve proporre ogni miglioria per integrazione agli autori originali. Il software non deve essere necessariamente ripubblicato a patto che tutte le personalizzazioni siano integrate dal team di sviluppo originale.
4. Il software, se personalizzato, dovrà essere pubblicato sulla propria piattaforma di code hosting e nuovamente registrato all’interno di Developers Italia.

In generale, rispetto a questo modello di riuso possiamo sottolineare che le Pubbliche Amministrazioni “A” e “B” non devono neppure contattarsi. La licenza libera regola le condizioni di utilizzo del software. Il software può essere scritto da uno sviluppatore e personalizzato da un altro, questo elimina i vincoli e i “lock-in”. La parte tecnica di pubblicazione è sempre demandata agli sviluppatori poiché è parte integrante del processo di sviluppo. Questo, quindi, è un sistema efficiente e a basso costo.

Scegliere una piattaforma di code hosting¶

Le pubbliche amministrazioni dovrebbero scegliere un sistema di controllo delle versioni basato sul sistema git, prendendo in considerazione l’utilizzo di una delle seguenti piattaforme di code hosting, in base alle loro funzionalità e all’adozione significativa da parte della comunità di software libero di riferimento.

Esistono piattaforme di code hosting sia on-premises che SaaS (anche a utilizzo gratuito). Tra queste ultime citiamo le più scelte tra i progetti liberi moderni:

• GitLab - https://gitlab.com
• GitHub - https://github.com
• Bitbucket - https://bitbucket.org
• Codeberg - https://codeberg.org/

All’interno di uno strumento di code hosting è possibile organizzare i propri progetti in modo gerarchico, creando un’organizzazione che conterrà all’interno tutti i singoli repository di software. Tale organizzazione può assumere un nome diverso in base alla piattaforma utilizzata: “organizzazione” nel caso di GitHub, “Group” per Gitlab e “Team” per Bitbucket.

Si può immaginare l’organizzazione come un raccoglitore dei singoli repository che a loro volta conterranno il codice sorgente.

È buona norma definire il nome dell’organizzazione in modo coerente rispetto all’ente che la sta creando. Ad esempio, prendendo l’ente fittizio creato come esempio chiamato “Comune di Réuso”, l’organizzazione potrebbe chiamarsi “comune-reuso” e contenere al suo interno tutti i repository con il software di titolarità del comune. È infatti ragionevole pensare che, ad esempio, il software per la gestione del protocollo informatico abbia uno spazio a sé stante diverso da quello del software usato per gestire la lavorazione delle pratiche ricevute via PEC.

Il seguente schema ad albero rappresenta una possibile strutturazione dei repository all’interno di una organizzazione.

comune-reuso
|--  software-protocollo
|      |-- LICENSE
|      |-- README
|--  software-pec
|      |-- LICENSE
|      |-- README

La modalità di creazione di tali organizzazioni differisce a seconda della piattaforma adottata.

Qui di seguito saranno elencate le modalità di creazione di una organizzazione all’interno di alcune tra le piattaforme elencate nelle linee guida.

GitHub¶

Un’organizzazione su GitHub può essere creata in modo molto semplice e gratuito direttamente tramite l’interfaccia online del servizio. Per creare un’organizzazione, è possibile seguire i seguenti passi:

1. Fare login su GitHub con le proprie credenziali

Aperto il sito https://www.github.com/ è possibile effettuare l’accesso selezionando sulla barra in alto a destra, il bottone “Sign In”.

Nella schermata che compare è possibile specificare il proprio nome utente e password o scegliere una modalità di accesso differente.

Se non si dispone di un utente è possibile selezionare “Create an account” per creare un nuovo utente sulla piattaforma.

2. Creare una nuova organizzazione

Per creare una nuova organizzazione è necessario selezionare il bottone “+“ a fianco dell’avatar del vostro utente e selezionare dal menù a tendina “New organization”.

3. Specificare le informazioni per l’organizzazione

Dopo aver specificato di voler creare una organizzazione, sarà possibile aggiungere le informazioni rilevanti. È necessario specificare:

• Organization account name: indicare il nome dell’organizzazione della PA, ad esempio comune-di-reuso, in modo che sia raggiungibile su https://github.com/comune-di-reuso.
• Contact email: specificare la mail di contatto per qualsiasi informazione riguardante l’organizzazione.
• Belongs to: indicare il nome di un ente al quale l’organizzazione sarà legata

Dopo una serie di passaggi di verifica, premendo sul tasto “Next” verrà richiesto quali account invitare all’interno dell’organizzazione e quale visibilità impostare (nel caso specifico suggeriamo “public”).

L’URL dell’organizzazione così creato sarà https://github.com/comune-di-reuso.

Aggiungere l’organizzazione a Developers Italia¶

Una volta ottenuta la propria organizzazione dallo strumento di code hosting la si può registrare nel Catalogo di software pubblico di Developers Italia, attraverso il sito https://onboarding.developers.italia.it. All’interno di questo portale si dovranno inserire le informazioni relative al referente e la URL dell’organizzazione dell’ente.

Questa operazione permetterà a Developers Italia di indicizzare automaticamente tutti i software dell’organizzazione in modo da renderli facilmente trovabili all’interno del Catalogo del software a riuso.

Scegliere il nome del progetto¶

La denominazione del progetto (e del repository associato) è una parte importante del rilascio.

Si suggerisce di:

• usare un nome descrittivo che chiarisca le finalità del progetto.
• non utilizzare marchi di terze parti se non quando necessario; ad esempio possono essere utilizzati come descrittori (ad esempio «Librerie di test per Java» anziché «Librerie di test Java»).
• non scegliere come nome di progetto un marchio registrato di proprietà altrui.
• per i nomi dei repository, separare le parole con trattini invece di concatenarle (ad esempio invece di “successortoserverless” utilizzare “successor-to-serverless”). Questo aumenta la leggibilità da parte di chi dovrà usare il software.

Scegliere e dichiarare la licenza¶

È fondamentale operare la scelta della licenza nel momento della nascita del progetto. Oltre al fatto che un progetto senza licenza non può essere considerato software libero (a prescindere dalla leggibilità del suo codice sorgente) possono emergere problemi nel caso dovessero sopravvenire modifiche o suggerimenti di miglioramento. In questo caso la licenza dei contributi non sarebbe chiara e questo potrebbe comportare controversie legali.

Inoltre, è importante evitare di usare la dicitura «Tutti i diritti riservati» o «All rights reserved», in quanto in contraddizione con l’apposizione di una licenza libera.

Per questo motivo ogni repository deve obbligatoriamente avere una licenza riportata nel file dedicato (chiamato normalmente LICENSE o LICENSE.md). In caso di conferimento iniziale, il file LICENSE può essere incluso direttamente nella prima pull request (come viene chiamato su molte piattaforme il meccanismo di proposta di modifiche) purché il commit sia effettuato dal soggetto titolare del codice.

Per indicazioni circa le licenze, si può fare riferimento alle “Linee guida su acquisizione e riuso di software per le pubbliche amministrazioni”, Allegato C: Guida alle licenze Open Source.

Accettare dei contributi dopo il rilascio¶

Dopo aver rilasciato un software libero per il riuso, è molto probabile che qualche altro soggetto o amministrazione la voglia utilizzare per i propri scopi. In questo riutilizzo, il codice potrebbe ricevere contributi di miglioramento, correzioni di errori o sviluppo di nuove funzionalità.

È bene che questi contributi siano accettati e integrati nel codice sorgente del progetto in modo da rappresentare un miglioramento per tutti coloro che sono interessati al suo riuso. Per accettare i contributi, tuttavia, occorre verificare alcuni aspetti:

• i contributi devono essere revisionati in termini di potenziali rischi per la sicurezza della soluzione;
• i contributi non devono riguardare personalizzazioni del software in questione non compatibili con un utilizzo generico da parte di terzi;
• è consigliabile che il titolare e mantenga il controllo dell’architettura e della qualità del software da lui prodotto e verifichi quindi che i contributi non violino regole di struttura o di organizzazione del progetto.

Gestione delle segnalazioni¶

Quando un utilizzatore trova una funzionalità mancante o un problema sul codice, può aprire una issue (segnalazione) per notificare un problema in modo che esso venga preso in considerazione e corretto.

L’Allegato B alle Linee guida su acquisizione e riuso di software per le pubbliche amministrazioni descrive proprio questi aspetti legati alla manutenzione di software libero.

I sistemi di versionamento del codice, solitamente, dispongono di meccanismi per registrare issue e per seguire la loro risoluzione. Quando si usano tali sistemi, è buona pratica che chi gestisce le issue risponda abbastanza tempestivamente alle segnalazioni indicando la presa in carico e specificando le modalità e le tempistiche con cui saranno risolte.

L’allegato alla linee guida descrive alcune interazioni tipiche che possono verificarsi sul sistema di code hosting di software libero:

• risoluzione di bug;
• richieste di nuove funzionalità;
• richieste di informazioni o supporto;
• contributi di codice.

L’Ente che ha rilasciato il software deve tendenzialmente occuparsi di garantirne il mantenimento, impostando il flusso di gestione e intervento sulle segnalazioni che provengono dall’esterno. Le segnalazioni, quindi, devono essere monitorate e prioritizzate. Si interverrà poi su alcune di esse, per risolverle e chiuderle.

Diverse issue possono essere prese in carico in un unico periodo e portare al rilascio di una nuova versione del software che le risolve tutte contemporaneamente. In questo caso il progetto lavora per milestone, e ogni milestone risolve un numero variabile di issue aperte nel periodo precedente.

Gestione delle richieste di modifica¶

Quando un contributore invia una richiesta di modifica al codice tramite pull/merge request il maintainer è tenuto a dare un riscontro tempestivo, anche solo per ringraziare il contributore in attesa della revisione del codice. Fornire un feedback immediato ai contributori aiuta a comunicare che il progetto è vivo e mantenuto e incoraggia altri contributi esterni. In questo modo, inoltre, si evita che, non vedendo riscontri, gli altri sviluppatori proseguano lo sviluppo in un proprio fork.

Dichiarazione di obsolescenza di un progetto¶

Può capitare che un repository non venga più mantenuto o esaminato e quindi non sia più di interesse, è tuttavia utile conservarlo per scopi di archiviazione e visualizzazione pubblica. In questo caso è importante denominare il repository come deprecated (obsoleto) in modo da segnalare che il progetto non è più attivo e mantenuto ma è conservato per scopi di archiviazione.

Preparare il progetto¶

Prima di rilasciare del codice come software libero è fondamentale prestare molta attenzione a ogni singolo contenuto che dovrà essere caricato sul repository e che di conseguenza diventerà pubblicamente fruibile. È quindi importante effettuare dei controlli preventivi a tutti i file (anche a quelli nascosti che a volte potrebbero sfuggire ad un’analisi superficiale) per assicurarsi che siano adatti alla visualizzazione pubblica. In tal senso, è importante porre attenzione anche ai commenti del codice: spesso, infatti, accade che nei commenti gli sviluppatori utilizzino un linguaggio inopportuno alla pubblicazione.

Inoltre, è bene accertarsi di alcuni principi elementari di sicurezza per verificare che il software sia ragionevolmente sicuro per essere rilasciato pubblicamente. Per esempio, è fondamentale porre particolare attenzione nel verificare che nel codice non siano state dimenticate delle password (nemmeno di ambienti di test o sviluppo).

Problema simile a quello delle password riguarda i token di autenticazione usati per alcuni servizi acceduti tramite rete.

Per ovviare a ciò è possibile usare dei rapidi stratagemmi. Ad esempio, per individuare nomi host, indirizzi di posta elettronica e indirizzi IP, è possibile eseguire questo comando in console:

egrep -r '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,6}\b"

\|([0-9]+\.){3}[0-9]+' ${SOURCE_PATH:=.}

Oppure, per trovare i commenti nei sorgenti in linguaggi Java/C/C++/Go/Objective-C/Objective-C++/Swift/Kotlin è possibile usare il seguente comando:

find ${SOURCE_PATH:=.} -type f \| egrep

'\.(c|cc|h|cpp|go|java|kt|m|mm|swift)' \| while read f; do echo

"------------ $f ------------------"; sed -n -e '/\/\*.*\*\// {p;

b}' -e '/\/\*/,/\*\//p' -e '/\/\//p' "$f"; done

Infine, per vedere i commenti in Python/Bash:

find ${SOURCE_PATH:=.} -type f \| egrep '\.(py|sh)' \| while read f; do
echo "------------ $f ------------------"; grep -o "#.*" "$f"; done

Questi sono solo alcuni esempi utili per trovare rapidi riscontri ma deve essere cura del maintainer effettuare dei controlli approfonditi in questa fase preparatoria alla pubblicazione.

Se è stato utilizzato il sistema di versionamento git fin dall’inizio dello sviluppo è fondamentale prestare attenzione al fatto che tutte le modifiche apportate ai vari file siano state tracciate e quindi visibili nella history. In tal senso, se vengono rimosse delle informazioni in fase di preparazione è fondamentale che le stesse informazioni siano rimosse anche dalla history. Per effettuare questo tipo di operazione esistono diversi strumenti. Il documento Removing sensitive data from a repository (scritto dalla piattaforma GitHub ma applicabile in generale a tutti i repository git) rappresenta una guida utile per rimuovere in sicurezza le informazioni sensibili dal proprio codice sorgente e, di conseguenza, dalla history del progetto.

Si raccomanda di eseguire alcuni controlli di base sulla qualità e sulla sicurezza del codice prodotto, utilizzando strumenti disponibili gratuitamente. Ad esempio, molti IDE moderni includono già strumenti di linting per controllare l’assenza sia di errori che di warning, per controllare l’esistenza della documentazione, eventuale codice non utilizzato, variabili non inizializzate e così via. È fortemente consigliato l’utilizzo di questo tipo di strumenti già in fase di sviluppo per trovare e rimuovere i problemi in fase embrionale. Inoltre, si suggerisce di inserire questi controlli (ad es., linting) anche nella propria toolchain di build. La ridondanza, in questo caso, può essere d’aiuto.

Numerosi sono gli strumenti di audit gratuiti che effettuano controlli di sicurezza e di qualità ulteriori per progetti di software libero. Come supporto per la scelta è possibile controllare le comparazioni degli strumenti sia FLOSS che di mercato in queste liste:

• Source Code Analysis Tools
• Source Code Security Analyzers

Come vedremo nel capitolo dedicato, alcuni di questi strumenti sono facilmente integrabili all’interno di diverse piattaforme di code hosting o di Continuous Integration: questo permette di eseguire una serie di controlli automatici per ogni operazione che viene eseguita sul repository (ad esempio, ad ogni commit) ed è quindi considerata una buona pratica.

Gestione delle dipendenze¶

Spesso, nello sviluppo di software, gli sviluppatori usano librerie scaricate localmente nella propria directory di sviluppo. Questa modalità, sebbene possa sembrare utile in fase di testing o prototipazione nell’ambiente di sviluppo locale, è considerata una cattiva pratica nello sviluppo di applicativi moderni. Essenzialmente un approccio di questo tipo comporta una forte difficoltà nella gestione sul lungo periodo, diversi problemi nell’aggiornamento di ogni singola dipendenza e l’impossibilità di usare strumenti automatizzati di rilevazione di vulnerabilità.

È invece buona pratica gestire le dipendenze esterne del software da rilasciare usando il gestore di pacchetti del linguaggio usato (ad es. npm, composer, ecc.). In questo modo le dipendenze e le loro versioni saranno dichiarate all’interno di un file tracciato da git e presente nel repository (ad es., package.json, ecc.) il che rende la loro gestione e l’aggiornamento più facile e immediato. Per un approfondimento è possibile consultare la sezione dedicata della 12 factor app (https://12factor.net/it/dependencies).

Inoltre, anche in questo caso esistono degli strumenti automatizzati che facilitano non solo l’aggiornamento delle singole dipendenze, ma anche la segnalazione di potenziali vulnerabilità in una particolare versione utilizzata. Questi strumenti sono spesso disponibili direttamente all’interno delle piattaforme di code-hosting o possono essere trovati sotto forma di plugin facilmente installabili. Le singole dipendenze vengono analizzate e, nel caso vi siano delle potenziali vulnerabilità, il maintainer verrà notificato e spesso la soluzione sarà suggerita in automatico.

Tra gli strumenti disponibili è possibile citare:

• npm-audit, strumento FOSS per la gestione delle dipendenze e notifica delle vulnerabilità per Javascript/Node.js
• Dependency Scanning GitLab, scanner integrato nella piattaforma (solo alcune versioni)
• Dependabot - ora integrato in GitHub
• Snyk, sistema proprietario in SaaS disponibile gratuitamente per progetti di software libero.

Molto software libero moderno è composto da numerosissime dipendenze, come ad esempio librerie di terze parti, e pensare di aggiornarle indipendentemente senza utilizzare degli strumenti di supporto è un’operazione molto esosa e incline ad errori. È perciò fortemente consigliato adottare le buone pratiche qui descritte sia per la gestione delle dipendenze tramite il gestore dei pacchetti che per quanto riguarda gli strumenti di supporto messi a disposizione dalle varie piattaforme.

Responsabilità di terzi¶

Le licenze chiariscono che gli autori del software non hanno nessuna responsabilità in merito alla completezza e funzionalità, e che è sempre l’utente a doversi assumere la responsabilità per l’adozione di tale codice.

Ad esempio, questo è quanto prevede la BSD-3:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

È dunque compito di chi sviluppa e mantiene il software rilasciato in come software libero assicurarsi che sia sicuro, privo di bug o di vulnerabilità, e quindi adottare strumenti finalizzati alla qualità del codice, come ad esempio: unit tests, CI, auditing, checklist per feature parity. Problemi o limitazioni note devono essere accuratamente documentati come issue, e nei casi più importanti anche esplicitati nel README.

I file da inserire nel repository¶

Il repository di un progetto libero contiene solitamente numerosi file. In particolare, è buona pratica inserirne alcuni come il README, il file LICENSE o il file AUTHORS, per permettere al visitatore di capire più nel dettaglio la natura di tale progetto senza dover leggere fin da subito il codice sorgente. Vediamo ora questi file più in dettaglio

Rilascio¶

Una volta creato il repository pubblico è necessario pubblicare tutto il codice sorgente contenente i file già elencati più sopra. Se il software da pubblicare è già stato scritto in modalità “chiuso”, è importante riportare tutti i commit passati in modo da facilitare l’interazione con i contributori terzi. Effettuare un singolo commit in modalità “bulk” è considerata una cattiva pratica, proprio perché non rende trasparenti le singole modifiche effettuate nel tempo dagli sviluppatori.

I messaggi di commit sono importanti in quanto comunicano in breve quali operazioni sono state effettuate dallo sviluppatore. Esistono anche in questo caso diversi approcci e buone pratiche. Una di queste è Conventional Commits che presenta il seguente formato:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Lo scopo è quello di trasmettere molte informazioni in modo semplice, che siano leggibili e interpretabili, sia da essere umani che da sistemi automatici. Anche in questo caso sarà dunque possibile sfruttare degli automatismi integrabili nelle piattaforme di code hosting o di Continuous Integration.

Dopo il rilascio, tutte le operazioni successive che verranno effettuate saranno pubbliche. Per prevenire la pubblicazione di altre informazioni sensibili oppure evitare di commettere errori prima del push sul repository è considerata una buona pratica l’utilizzo di sistemi di controllo pre-commit. Tali sistemi, come ad esempio https://pre-commit.com/, si possono installare negli ambienti locali di sviluppo e permettono di eseguire una serie di controlli prima di effettuare il commit o il push: in questo modo la pubblicazione viene bloccata fino a che il problema non è risolto.

L’importanza del ruolo del maintainer¶

Il maintainer di un progetto di software libero è un ruolo con molteplici funzioni organizzative e pratiche. Essenzialmente, il maintainer ha il completo controllo di un repository, potendo effettuare le operazioni di clone, push, merge, creazione di nuovi branch e così via. È la persona responsabile della manutenzione ordinaria del contenuto del repository, ovvero colui che si impegna a seguire l’evoluzione del software, effettuando le operazioni tipiche di housekeeping: si assicura che i diversi approcci vengano seguiti, assicura che il gitflow scelto venga rispettato, che il versionamento sia coerente con le scelte e così via. Inoltre il maintainer di un progetto libero nella maggioranza dei casi ha a che fare con la community, ovvero l’insieme degli utenti o dei contributori che interagiscono con il repository. Questa figura, infatti, segue l’evoluzione delle issue, dirige correttamente i contributori facendo seguire quanto presente nel file CONTRIBUTING, e opera i merge delle Pull Request. A volte il maintainer fa parte del team di sviluppo e può quindi effettuare direttamente le review dei contributi mentre altre volte si avvale del supporto degli sviluppatori per effettuare revisioni e consolidare i contributi. Il maintainer è dunque un ruolo fondamentale con numerose responsabilità sulla vitalità del progetto.

Non sempre il maintainer è unico, spesso infatti questo ruolo è assunto da un team di persone che hanno lavorato sul progetto per un determinato lasso di tempo e che dunque sono considerati affidabili.

Versionamento e rilasci¶

Esistono diversi approcci al versionamento del software e alla gestione dei rilasci.

Un possibile approccio è quello di non effettuare una vera e propria pubblicazione di rilasci ufficiali e numerati in quanto git è già di per sé un sistema di versionamento ed in molti casi è sufficiente. Questa scelta è percorribile nei seguenti casi:

• progetti di piccole dimensioni;
• componenti destinati ad altri sviluppatori (asset grafici, toolkit, template…), unicamente nel caso di progetti interni;
• progetti che adottano strategie di Continuous Delivery per i quali vale quindi sempre e solo l’ultima versione.

Al contrario, i rilasci ufficiali tradizionali sono tipicamente necessari in queste situazioni:

• software destinato ad un’ampia platea di utenti finali;
• software che richiede compilazione e quindi distribuzione in forma binaria;
• software che necessita di testing non automatizzabile (audit ecc.);
• software da rilasciare anche su altre piattaforme di distribuzione (npm, Maven Central, ecc.);
• software allineato a schemi di versionamento esterni (ad esempio per aggiornamenti della normativa);
• software per il quale viene mantenuta documentazione separata (in modo da sapere quale versione consultare per una determinata versione del software);
• software che può prevedere modifiche non retrocompatibili, con una base di utenti che può rimanere potenzialmente legata a precedenti versioni.
• software da utilizzare in architetture complesse (ad es. i componenti di un sistema a microservizi).

Se si sceglie di procedere con una strategia di rilascio, è necessario essere molto rigorosi nell’eseguire i rilasci con regolarità e tempestività (release early, release often): una volta adottati, non sono facoltativi.

Ad esempio, nella piattaforma GitHub è possibile usare la funzione delle milestone per associare le issue ai futuri rilasci, in modo da documentare cosa manca per procedere con un rilascio. Si deve infatti evitare che vi siano delle novità nella base di codice non ancora rilasciate ufficialmente, senza che vi sia alcuna indicazione di cosa stia aspettando il maintainer a rilasciarle.

A seconda che si adotti uno dei due modelli o l’altro, il significato del branch master (o main) è diverso. In assenza di rilasci, è solitamente sottinteso il principio dello stable master branch, ovvero: il branch master deve sempre contenere codice stabile ed utilizzabile, pertanto non può essere usato per sviluppo di funzionalità non testate. È necessario separare lo sviluppo in branch separate da portare su master attraverso Pull Request separate. Eventualmente, nei casi più delicati si può anche pensare ad un branch develop verso il quale indirizzare le Pull Request, e poi avere un processo di testing più approfondito per portare le modifiche da develop a master.

Al contrario, in presenza di rilasci non è strettamente richiesto che il branch master sia stabile (a quello scopo servono appunto i rilasci, spesso accompagnati dalla creazione di un branch stabile), ma è comunque bene adottare la pratica di lavorare in branch separati quando si eseguono refactoring o comunque grandi modifiche.

Nel caso in cui si scelga di associare una numerazione ai singoli rilasci, il versionamento semantico (https://semver.org/) è un buon esempio da seguire quando possibile.

Il versionamento semantico definisce un numero di versione composto da tre numeri: MAJOR.MINOR.PATCH. I corrispondenti numeri di versione devono essere incrementati in questo modo:

• MAJOR: quando si apportano modifiche API/ABI incompatibili con le precedenti;
• MINOR: quando si aggiunge funzionalità in modo compatibile con le versioni precedenti;
• PATCH: quando si apportano correzioni di bug compatibili con le versioni precedenti.

Ulteriori prefissi o postfissi al numero di versione (come pre-release e build) possono essere utilizzati per segnalare versioni particolari in momenti chiave del progetto.

Issue¶

L’issue tracker è uno degli strumenti messi a disposizione da molte piattaforme di code hosting per permettere agli interessati di comunicare con il team di sviluppo. Esempi di issue possono essere: segnalazioni di problemi, richieste di aggiunta di nuove funzionalità o discussioni relative al progetto. A questo proposito, è molto importante che lo strumento sia disponibile e aperto a contributi. Se questa condizione non dovesse essere soddisfatta è possibile indicare nel README il percorso per raggiungere lo strumento di issue tracking da usare come riferimento.

I maintainer hanno il compito di monitorare la sezione delle issue e di dare un tempestivo riscontro, non necessariamente entrando nel merito della questione: avere a che fare con un repository seguito e non abbandonato incentiva gli altri membri della community ad entrare nella discussione e contribuire “investendo” il proprio tempo nel progetto.

Accettare i contributi dopo il rilascio¶

Una volta rilasciato il codice sorgente in modo pubblico è possibile che dei contributori di terze parti, ovvero non facenti parte del contingente originale che ha sviluppato il software, apportino delle modifiche al codice.

Tali contributi possono avvenire tramite un meccanismo chiamato Pull Request (PR) o Merge Request (la nomenclatura varia al variare della piattaforma utilizzata per la pubblicazione). La Pull Request è una richiesta, fatta all’autore originale di un software, di includere modifiche al suo progetto.

Quando una nuova Pull Request viene aperta, la piattaforma notifica al maintainer che è necessario affrontare le operazioni di revisione.

Integrazione Continua (Continuous Integration)¶

I sistemi di integrazione continua (Continuous Integration, CI) sono utili per ridurre i tempi di ricerca di bug, consentendo di effettuare test automatizzati dell’intera code base. Ciò è particolarmente utile per i progetti che coinvolgono una grande comunità di sviluppatori. Tuttavia è buona norma dotarsi di tali strumenti fin dall’inizio dello sviluppo.

Inoltre, ogni modifica proposta tramite il meccanismo delle Pull/Merge Request deve “passare” una serie di test automatici prima di essere anche solo presa in considerazione dai maintainer. I processi di CI rappresentano un supporto di fondamentale importanza sia in fase di sviluppo, per identificare eventuali problemi o migliorare la qualità generale del codice, che in fase di analisi dei contributi esterni, per validare le proposte e evitare di effettuare numerose interazioni con i contributori su codice che non è stato accuratamente allineato con le esigenze del progetto.

Esistono molti esempi di questi sistemi di integrazione continua. Tra i più utilizzati citiamo:

• Jenkins CI, particolarmente adatto a deployment locali (installazione on-premises)
• Gitlab CI, integrato con la piattaforma di code-hosting GitLab
• Circle CI, servizio proprietario, disponibile come SaaS gratuitamente per i progetti di software libero
• GitHub Actions

La particolarità di questi sistemi è che si integrano perfettamente con le piattaforme di code hosting più comuni e permettono quindi di eseguire una serie di test e/o controlli automatici per ogni singola azione che viene eseguita sulla codebase (ad es., commit, merge etc.).

Normalmente la configurazione di questi sistemi richiede la presenza di un semplice file di configurazione da posizionare nella cartella radice del repository. In tal senso, il Team di Developers Italia ha realizzato alcuni template pronti all’uso, per testare ad esempio il file publiccode.yml, ma che si possono facilmente estendere per essere utilizzati in altri contesti.

• Qui puoi trovare il publiccode-parser-orb per CircleCI: https://github.com/italia/publiccode-parser-orb
• Qui puoi trovare la action da integrare nel tuo repository github: https://github.com/italia/publiccode-parser-action

Elenchiamo di seguito le principali possibilità che un sistema di Continuous Integration offre:

• esecuzione di test automatici (sia unitari che End-to-End);
• audit di sicurezza con sistemi di SAST;
• analisi della qualità del codice;
• analisi della quantità di codice coperto da test unitari (code coverage), importantissima funzionalità per garantire un codice di qualità;
• analisi dei messaggi di commit (commit-lint).

Oltre a queste analisi, che possono offrire una panoramica sullo stato di salute del codice in ogni momento utile,c’è anche la possibilità di automatizzare numerose operazioni come ad esempio:

• effettuare dei rilasci automatici (tag e release);
• effettuare la compilazione dei sistemi con le informazioni di produzione (build);
• effettuare delle operazioni di interazione con altri sistemi web tramite API, ad esempio le immagini docker possono essere inviate a dei registri pubblici.

Infine, l’ultimo passaggio interessante, anche denominato Continuous Deployment (CD), consiste nell’utilizzare questi strumenti anche per effettuare il deploy, quindi la messa in produzione, del sistema. Il concetto fondamentale in questo caso è quello di utilizzare la stessa codebase per tutti i deployment che verranno effettuati (ad esempio, development, staging, pre-prod, live) dove a variare saranno solo le risorse connesse all’applicazione (ad es., i DB) tramite opportuni file di configurazione (maggiori approfondimenti sono disponibili su 12factor app).

Abbiamo visto come i sistemi di CI possono facilitare la vita dello sviluppatore, aumentare la qualità del codice, supportare le analisi di sicurezza e, infine, effettuare la messa in opera dell’intero sistema in modo completamente automatico: possono sicuramente essere considerati il coltellino svizzero dello sviluppo di software libero.