Come e perché automatizzare il controllo qualità nello sviluppo software

Scopriamo i vantaggi della Continuous integration (CI) per la gestione del ciclo vita dei nostri progetti Open Source

Di

Fabio Bonelli

Photo by Karla Hernandez on Unsplash

Quando sviluppiamo un software ci troviamo di frequente dinanzi alla necessità di apportare modifiche, miglioramenti, aggiungere o rimuovere funzionalità che potrebbero fare emergere nuovi problemi e anomalie apparentemente inspiegabili, per questo motivo è necessario condurre attente analisi e collaudi (riproducibili e deterministici) prima di reputare il nostro lavoro idoneo al rilascio.

Quante volte ci è successo di dover correggere un problema in emergenza, perdendo molto più tempo di quello che avremmo speso se fossimo stati avvisati per tempo? Se qualcuno — o qualcosa — ci avesse indicato la presenza di un possibile errore nel codice prima che questo fosse messo in produzione, probabilmente non avremmo dovuto apportare modifiche urgenti sotto pressione e durante il processo di sviluppo saremmo stati più confidenti e rapidi nell’inserire nuove funzionalità.

Una pipeline di continuous integration (CI) con test automatici può diventare quel qualcuno (o qualcosa in questo caso!), che rileva un problema prima che questo diventi un errore in produzione, consentendoci di lavorare più serenamente e di diminuire il tempo passato successivamente a correggere bug. Grazie a questa pipeline, gli sviluppi locali del software sono costantemente sottoposti a test automatici e le modifiche che potenzialmente introducono criticità immediatamente segnalate. La suite consente al software di essere testato automaticamente sia a livello di singoli componenti (unità di test) che nella sua interezza (test funzionali e di integrazione) consentendo ai suoi autori di rilevare eventuali difetti di funzionamento anche in relazione all’ambiente di esecuzione (versione del sistema ospite) o a dipendenze di terze parti.

I test automatizzati di un software sono essenziali per valutarne la robustezza, per facilitare l’individuazione e soluzione di bug, e cosa spesso sottovalutata, per facilitare le contribuzioni.

Un contributore esterno al progetto, dopo aver modificato qualcosa, facendo i test, potrà essere ragionevolmente certo di non aver cambiato involontariamente il comportamento del software in sezioni non volute e il maintainer sarà facilitato nel revisionare la contribuzione che passa i test.

Aggiungere test è anche un ottimo modo per segnalare e documentare bug o comportamenti anomali. Aggiungere test di solito elimina o attenua la necessità di corredare i bug con lunghe descrizioni, screenshot, dati di esempio, particolari sull’ambiente di esecuzione.

Piattaforme di sviluppo come GitHub, GitLab e CircleCI ci offrono strumenti d’avanguardia per automatizzare i test che possiamo integrare nel nostro progetto di sviluppo. In questo articolo parliamo di come utilizzare questi strumenti prendendo spunto dall’esempio di validazione dei file publiccode.yml all’interno dei nostri repository, e utilizzando le pipelines e gli strumenti già realizzati dal team di Developers Italia.

Cos’è publiccode.yml

publiccode.yml è uno standard internazionale creato dal Team per la Trasformazione Digitale nel 2018: esso consiste in un file YAML utilizzato per descrivere il software open source. Secondo le Linee Guida pubblicate nel 2019 deve essere utilizzato da tutte le Pubbliche Amministrazioni in fase di pubblicazione per descrivere il proprio software, in modo da agevolare una comoda ricerca da parte di altri enti nel catalogo di Developers Italia. Questo catalogo può essere usato tanto da enti pubblici che da privati, e raccoglie i software open source usati nella Pubblica amministrazione, nonché le migliori soluzioni messe a disposizione dal mondo open source.

Questo file si trova tipicamente nel repository di codice del software stesso. Oltre a un comodo editor online, esiste un validatore che verifica la correttezza formale del file stesso. Le modifiche a questo file non sono frequenti, tuttavia è possibile introdurre inavvertitamente degli errori di cui ci si può non accorgere immediatamente.

Il suo formato machine-readable lo rende un perfetto candidato per essere verificato in automatico. Quindi, perché non controllarlo in automatico ad ogni commit?

publiccode.yml durante lo sviluppo

Una volta che inseriamo publiccode.yml nel repository lo dobbiamo tenere aggiornato: basti pensare, per esempio, a quando rilasciamo una nuova versione del nostro software, oppure a quando vogliamo aggiungere nuove informazioni facoltative che prima non avevamo compilato.

In questi casi dobbiamo modificare il file e come sappiamo, gli aggiornamenti possono portare con sé degli errori che, se non rilevati immediatamente, verrebbero di conseguenza pubblicati sul catalogo di Developers Italia — o ancora peggio — comporterebbero una temporanea sospensione dalla pubblicazione.

Come usare le pipeline di Developers Italia

Developers Italia ha preparato e utilizza degli strumenti di controllo per i publiccode.yml da inserire in CI per i principali code hosting: GitHub, GitLab e CircleCI.

Vediamo come si possono integrare.

GitHub Actions

Photo by Roman Synkevych 🇺🇦 on Unsplash

GitHub usa un sistema per l’automazione chiamato GitHub Actions: questo sistema permette di automatizzare controlli e azioni su un repository di software, come, per esempio, il controllo del rispetto di buone pratiche condivise tra il team di sviluppo o l’esecuzione di test automatici. Developers Italia ha sviluppato una Action per il controllo e la validazione dei file publiccode.yml.

È possibile aggiungere tale Action direttamente dal proprio repository su github.com, tramite la linguetta “Actions”:

Da lì si può aggiungere un file chiamato .github/workflows/main.yml

on: [push, pull_request]
jobs:
    publiccode_yml_validation:
        runs-on: ubuntu-latest
        name: publiccode.yml validation
        steps:
            - uses: actions/checkout@v2
            - uses: italia/publiccode-parser-action@v0.0.2-alpha
              with:
                  publiccode: publiccode.yml

La Action girerà a ogni commit o Pull Request, fallendo in caso di errori nel publiccode.yml.

GitLab

Se si usa GitLab, basta aggiungere un file .gitlab-ci.yml nella directory principale del repository con questo contenuto:

include:
    - https://raw.githubusercontent.com/italia/publiccode-parser-gitlab-ci/main/publiccode-validation.yml

CircleCI

Se si usa CircleCI ci sono due parti da modificare nel proprio file .circleci/config.yml:

1. una nella sezione orb per importare l’orb:

orbs:
     publiccode-parser: italia/publiccode-parser@0.0.3

2. la seconda nei workflows, avendo ora a disposizione il job “publiccode-parser/validate”

Ad esempio:

workflows:
    publiccode_yaml_validation:
        jobs:
            - publiccode-parser/validate

E con queste semplici righe, scelte a seconda del sistema utilizzato, abbiamo finito! Il sistema di Continuous Integration è ora un guardiano in più per il nostro codice, che instancabilmente testerà ogni modifica e si occuperà di notificarci adeguatamente (in modi diversi a seconda della loro interfaccia) qualora introducessimo inavvertitamente dei bug o delle inconsistenze nel nostro publiccode.yml.

Questo appena mostrato è solo un esempio sull’uso di una CI per una piccola parte del nostro repository, ma possiamo usarla per fare test automatici su molti altri aspetti: sul nostro codice, sulla sua sicurezza e sulla sua qualità.

Per maggiori informazioni documentati sui sistemi di CI più popolari:

• GitHub Actions: https://docs.github.com/en/actions
• GitLab CI/CD: https://docs.gitlab.com/ee/ci/
• CircleCI: https://circleci.com/docs/2.0/about-circleci/#section=welcome

Tutto il codice degli strumenti di Developers Italia è software libero ed è pubblicato su GitHub ai seguenti indirizzi:

https://github.com/italia/publiccode-parser-action (GitHub Action)

https://github.com/italia/publiccode-parser-gitlab-ci (GitLab CI)

https://github.com/italia/publiccode-parser-orb (CircleCI)

Qui puoi trovare un repository che usa la GitHub Action, come fonte di ispirazione: https://github.com/italia/design-wordpress-theme.

Conclusioni

Il tuo codice è ora sotto controllo automatico, e se per caso ti capiterà di introdurre un errore, avrai un sistema di allerta preventivo che ti segnalerà il problema. Il controllo riguarda per ora il solo file publiccode.yml, ma questo stesso procedimento può essere integrato per molti altri tipi di controlli. Qui ad esempio trovi una lista curata di altre Github Actions che puoi trovare utili.

Adesso che sai come dare più valore al tuo lavoro ed al tuo tempo costruisci anche tu una CI e migliora il tuo software! Ma non solo, se stai realizzando un applicativo open source inserisci un file publiccode.yml e monitoralo con i nostri strumenti.

Come per tutti i nostri repository, se dovessi notare o riscontrare dei problemi nel loro utilizzo inviaci i tuoi suggerimenti su Slack Developers (canale #publiccode) e, se ti senti un eroe, contribuisci agli strumenti di Developers Italia su GitHub.