Permalink
e5a8fa3 May 22, 2018
1 contributor

Users who have contributed to this file

480 lines (349 sloc) 23.6 KB

Contribuire al progetto

Grazie per l'interesse mostrato nei confronti del progetto ! 🎉

Cittadinanza Digitale è un progetto aperto a tutti: sono benvenuti contributi, suggerimenti e richieste di nuove caratteristiche.

Sebbene lo scopo precipuo sia erogare un servizio per i Cittadini, tra gli obiettivi del progetto si pone quello di fornire alle Amministrazioni e ai loro fornitori software "pronto da utilizzare": un prezioso strumento che faciliti l'integrazione con le "piattaforme abilitanti " previste dal piano triennale per l'informatica nella PA.

Cittadinanza Digitale, pertanto, non solo abbraccia il paradigma open source e del riuso così come proposto nella community di developers.italia.it, ma vuol porsi come implementazione di riferimento per l'integrazione con i sotto-sistemi:

A tale scopo è importante l'aiuto di tutti: solo tramite un processo di miglioramento continuo sarà possibile raggiungere alti standard che riguardano:

  • la qualità del software e della documentazione a corredo
  • la sicurezza delle componenti del sistema
  • un'esperienza utente efficace e soddisfacente, che segua i principi sulla progettazione dei servizi dettati da designers.italia.it

Quel che segue è un insieme di linee guida per poter contribuire all'evoluzione delle componenti che costituiscono il frontend (App mobile) e il backend (API) di Cittadinanza Digitale, scrivendo codice o integrando la documentazione, nonché una descrizione della metodologia di lavoro che vuol esser trasparente (e possibilmente esemplare 😉).

Come segnalare un bug o proporre una feature

Se hai domande o proposte ti suggeriamo di condividerle sul forum nella sezione dedicata: https://forum.italia.it/c/progetto-io/

In alternativa puoi trovarci su Slack nel canale #io-pa di developers.italia.it.

Risorse

Lo sviluppo dell'app e del suo backend avviene su GitHub.

Prima di iniziare ti consigliamo di leggere i README contenuti nella directory radice dei repository elencati in questa sezione. Potrai trovare:

  • la descrizione dell'architettura del backend e le scelte che ne hanno portato la definizione
  • la descrizione dettagliata del funzionamento del software e l'interazione tra le componenti
  • le procedure per sviluppare localmente e le dipendenze da installare

Repository GitHub

Repository principale con la descrizione dell'infrastruttura:
https://github.com/teamdigitale/digital-citizenship

Sorgenti delle API di notifica / preferenze (Azure Functions):
https://github.com/teamdigitale/digital-citizenship-functions

Sorgenti dell'App mobile:
https://github.com/teamdigitale/italia-app

Sorgenti del backend dell'App:
https://github.com/teamdigitale/italia-backend

Sorgenti del proxy per le API di PagoPa:
https://github.com/teamdigitale/italia-pagopa-proxy

Sorgenti del client API PagoPA:
https://github.com/teamdigitale/italia-pagopa-api

Utilità per l'onboarding nel developer portal:
https://github.com/teamdigitale/digital-citizenship-onboarding

Sorgenti del sito web di presentazione dell'App:
https://github.com/teamdigitale/italia-landing

Sito web dell'App

Sito Web rivolto ai Cittadini per spiegare i benefici dell'App:

io.italia.it

Pianificazione delle attività: Pivotal Tracker (ITA)

Per pianificare le attività e tracciarne il progresso utilizziamo Pivotal Tracker scrivendo in italiano.

Esiste un progetto su Pivotal Tracker per ogni componente sviluppata (o ancora da sviluppare :-).

I membri di uno specifico progetto hanno in carico la creazione delle singole attività. Le attività vengono inizialmente inserite nella "Icebox" dopodiché quelle considerate più urgenti sono spostate nel "Backlog". Chi lavora su un progetto sceglie un'attività dal backlog e la assegna a sè stesso quando inizia a lavorarla.

Può capitare che sia il maintainer del singolo progetto ad assegnare le attività ai membri; questi riceveranno una notifica al momento dell'assegnazione.

Gli stati di lavorazione assegnabili a ogni "feature" sono:

  • started: l'attività è stata presa in carico ed è ora in lavorazione
  • finished: è stata effettuata una Pull Request che è in attesa di Code Review
  • delivered: la Pull Request ha passato la Code Review
  • accepted: la PR è stata incorporata nel branch "master" e il codice è in esecuzione sull'ambiente di test

Le attività possono esser classificate come:

  • feature: attività che corrispondono a "user stories"; sono espresse necessariamente nella forma Come <.. personas... > voglio <... feature da implementare ...> in modo da <... valore aggiunto ...>
  • chore: attività che non portano direttamente un valore aggiunto per gli utenti del sistema, ma risultano utili nella fase di sviluppo (es. refactoring, modifiche dell'infrastruttura)
  • bug: un malfunzionamento che deve essere corretto
  • release: milestone il rilascio in produzione di una specifica versione del componente

Gli attori del sistema (personas) che utilizziamo nelle user stories sono:

  • CIT: i Cittadini che interagiscono con il frontend (es. App mobile)
  • SAS: soggetti aderenti al sistema; ad esempio le PA che possono utilizzare le API di notifica e preferenze
  • AMS: l'amministratore del sistema (Team Digitale / AgID / gestore del servizio)

Ogni attività appartiene a una epic (es. epic-security) che la colloca in uno specifico contesto. Le chore trasversali a più epic sono classificate nella epic epic-technical-debt.

Crea sempre un issue su Pivotal Tracker prima di iniziare a lavorare su un'attività !

Come buona pratica ogni attività deve essere atomica e realizzabile in un tempo relativamente breve (indicativamente: max 7gg).

Ovunque possibile evita di creare attività che ne comprendono più di una al loro interno. Ad esempio una Feature del tipo:

Come CIT voglio visualizzare la lista completa dei miei metodi di pagamento (solo carte di credito), la lista delle opearazioni di pagamento associate a ciascun metodo, i dettagli di ciascuna operazione e una pagina statica di aiuto sul portafoglio

va necessariamente divisa in quattro attività differenti.

Altre best practice nella pianificazione delle attività:

  • crea sempre una issue corrispondente a ogni commento "TODO" o "FIXME" nel codice
  • assegna sempre una epic alle issue (al limite: epic-technical-debt)
  • imposta sempre eventuali issue bloccanti (blockers)
  • crea sempre l'attività di granularità maggiore, completabile nel più breve tempo possibile
  • ogni attività deve poter avere un criterio chiaro per poter essere considerata terminata
  • non lasciare le issue aperte troppo a lungo

Lista dei progetti su Pivotal Tracker

Frontend - Pivotal Tracker

Backend - Pivotal Tracker

Backoffice - Pivotal Tracker

Analisi e progettazione

Google Drive (ITA)

Per analizzare le decisioni da intraprendere che hanno un impatto sull'architettura del sistema o sull'organizzazione del software utilizziamo l'editing collaborativo di documenti (CDM - Cittadinanza Digitale Memos, in italiano) tramite Google Drive:

CDM.

I task trasversali alle diverse attività quali logging, autenticazione, integrazioni tra componenti, etc. vengono inizialmente schematizzati in uno specifico documento che viene condiviso con il resto del team. Tutti i membri sono invitati a elaborare proposte e/o porre domande sugli aspetti meno definiti tramite gli strumenti forniti da Google Docs.

Lo stesso meccanismo viene usato per attività di alto livello che non riguardano necessariamente lo sviluppo del software; ad esempio: tutto ciò che concerne aspetti legati alla normativa o all'interazione con soggetti pubblici.

Limitatamente alle decisioni che riguardano l'architettura, queste vengono successivamente documentate (in inglese) in Architecture Decision Record (ADR):

ADR.

Comunicazione

Slack

Per le comunicazioni sincrone utilizziamo Slack:
slack.developers.italia.it

Sul canale #io-devel trovi i membri del team di sviluppo e i maintainer dei sotto-progetti, oltre a coloro che si occupano di aspetti non direttamente legati allo sviluppo (product management, esperienza utente (UX), coordinamento).

Il canale #io-pa è invece dedicato al supporto per fornitori e tecnici delle Pubbliche Amministrazioni aderenti al servizio.

Alcune regole per le discussioni in chat:

  • usa i thread per raggruppare messaggi afferenti uno stesso argomento o attività
  • menziona i membri interessati ai messaggi utilizzando la sintassi @<nome>
  • limita l'utilizzo di @channel solo a comunicazione particolamente urgenti

Daily scrum: Howdy

Su Slack, gli sviluppatori e i maintainer dei singoli progetti ricevono quotidianamente, alle 10:00 del mattino (GMT+1), alcuni messaggi privati provenienti da un bot Howdy: è obbligatorio rispondere ai messaggi ogni giorno, anche in maniera sintentica, in modo da comunicare al resto del team le attività svolte, ancora da svolgere ed, eventualmente, se vi sono impedimenti bloccanti.

Weekly meeting: Google Meet

I membri del team sono invitati a partecipare ai Google Meet pianificati con cadenza settimanale:

Durante le conferenze vengono condivise le informazioni con i maintaner di progetto in modo da pianificare le attività per la settimana e prendere decisioni sulle questioni ancora aperte.

Sviluppo e rilascio del codice

Tutto il codice è pubblicato su GitHub.

L'ambiente cloud attualmente utilizzato per il dispiegamento dell'infrastruttura è Microsoft Azure. Nel repository principale sono presenti gli script Terraform che permettono di replicare l'intera infrastruttura su un qualsiasi account Azure.

L'amministratore fornisce un account per accedere all'ambiente di test ai membri del team che lavorano a una specifica componente. L'account appartiene alla subscription Azure utilizzata per il progetto.

Nei README degli specifici progetti troverai le istruzioni da seguire per poter predisporre un ambiente di sviluppo locale.

Principi generali per lo sviluppo del codice

Ogni sotto-progetto ha le proprie "regole" (definite nello corrispondente README) che variano a seconda delle tecnologie e dei linguaggi impiegati.

Alcune buone pratiche da applicare durante la stesura del codice risultano tuttavia trasversali ai diversi progetti:

  • non utilizzare classi se non assolutamente necessario; tieni separati dati (strutture) e comportamenti (funzioni)
  • utilizza sempre tipi strutturati: non passare in input alle funzioni dati non strutturati (es. JSON o request.Express)
  • utilizza tagged types e tipi algebrici al posto delle classi
  • utilizza discriminated unions al posto dell'ereditarietà
  • privilegia strutture immutabili: usa const al posto di let, map / filter al posto dei cicli for o while, spread operator al posto di assegnamenti diretti, etc.
  • se usi le classi non fornire metodi setter: fa in modo che tutti i membri siano readonly
  • privilegia l'utilizzo di funzioni "pure"
  • utilizza Option ed evita i check su null / undefined
  • per gestire gli errori ritorna degli Either al posto di lanciare Eccezioni
  • utilizza le Promise al posto delle callback per il codice asincrono. limita l'utilizzo delle callback all'interazione con librerie esistenti
  • considera l'utilizzo di async / await al posto di then se può rendere il codice più leggibile

Per il codice Typescript utilizza:

  • italia-ts-commons per la definizione dei tipi personalizzati (NonEmptyString, DateFromString, EmailString, etc.)
  • io-ts per la definizione dei tipi e la validazione a runtime
  • fp-ts per l'implementazione di Option ed Either

Se devi introdurre un nuovo tipo, controlla sempre che non sia già presente in italia-ts-commons.

Per quanto riguarda le API, i tipi vengono estratti dallo schema JSON (OpenAPI) e convertiti nella loro rappresentazione Typescript / io-ts tramite i tool forniti dal pacchetto italia-utils.

Per la progettazione delle specifiche API (swagger / OpenAPI) ci ispiriamo alle
linee guida di Zalando per le scrittura di API.

Gestione degli errori tramite Either od Option

Alcune regole generali per la gestione degli errori:

  • se una funzione può ritornare un valore null o undefined, il tipo di ritorno sarà una Option
  • se una funzione può ritornare un errore, il tipo di ritorno sarà un Either<ErrorType, ResultType>
  • se una funzione può ritornare un errore oppure un valore null o undefined, il tipo di ritorno sarà Either<ErrorType, Option<ResultType>>
  • se la funzione è asincrona, il tipo di ritorno sarà una Promise di uno dei tre suddetti tipi

Per quanto riguarda il naming delle variabili suggeriamo i seguenti pattern:

Tipo del valore ritornato da f() Nome della costante
Option<ResultType> const maybeResult = f(...)
Either<ErrorType, ResultType> const errorOrResult = f(...)
Either<ErrorType, Option<ResultType>> const errorOrMaybeResult = f(...)

dove Result va sostituito con un nome adeguato al contesto.

Puoi trovare un esempio di questi pattern nel codice di alcuni controller Express già implementati: https://github.com/teamdigitale/digital-citizenship-functions/blob/master/lib/controllers/messages.ts#L262

Editor: linting e indentazione

Sei libero di utilizzare qualsiasi editor di testo. Tuttavia, all'interno di alcuni repository, troverai delle configurazioni per Visual Studio Code (VSC). VSC è un editor open source e possiede alcune caratteristiche imprescindibili per lo sviluppo di questo progetto:

  • un ottimo supporto per Typescript
  • un'efficace integrazione con tslint
  • il supporto all'indentazione on-save tramite prettier

Se sei indeciso su quale editor usare, ti consigliamo pertanto di provare VSC.

Prima di ogni PR, assicurati che tutto il codice Typescript (o Javascript) sia indentato tramite prettier. La configurazione è contenuta nei file .prettierrc presenti nella directory radice dei progetti. Se usi VSC, integra prettier nell'editor tramite la relativa estensione.

Qualità del codice

Per monitorare la qualità del codice usiamo alcuni tool per i quali è stata predisposta l'integrazione automatica al momento del rilascio su GitHub:

  • Codecov: percentuale di copertura degli unit test
  • Codacy: qualità del codice
  • Codeclimate: manutenibilità del codice
  • Snyk: sicurezza delle dipendenze npm

Monitora sempre i report associati alle Pull Request e attua le modifiche necessarie o suggerite dai tool di monitoraggio.

Test

Ogni funzionalità richiede la stesura di unit test corrispondenti.

La code coverage richiesta è alta (> 90%). Puoi far riferimento ai test già contenuti nelle directory __tests__ esistenti per scriverne di nuovi.

I file contenenti gli unit test hanno il formato <file_sorgente>.test.<estensione>, ad esempio errors.test.ts e sono contenuti nelle directory __tests__ presenti allo stesso livello dei sorgenti.

Gli unit test vengono eseguiti tramite Jest, sia durante lo sviluppo locale che durante le build automatiche via CircleCI.

Rilascio del codice su GitHub

Pull Request

Su GitHub scriviamo in inglese (issue, commenti, descrizioni delle Pull Request).

L'evoluzione dei componenti avviene integrando nuovo codice tramite Pull Request:

  1. scegli una issue su Pivotal Tracker e segnala come "Started"
  2. integra il tuo codice in un nuovo branch chiamato <id issue Pivotal>-<descrizione in inglese della issue> ad esempio 123456-fix-api-response
  3. includi sempre all'inizio della descrizione (in inglese) dei commit e nei titoli delle Pull Request il numero di issue Pivotal corrispondente nel formato [#<id issue>], es. [#123456] fixed api response
  4. quando sei a buon punto, anche se non hai terminato il lavoro, effettua una Pull Request in modo che gli altri membri del team possano visualizzare le tue integrazioni; includi un marcatore WIP (work in progress) nei titoli di queste PR es. [#123456] WIP: fix api response
  5. includi nelle PR una descrizione delle modifche introdotte, il perché sono necessarie e altri dettagli che aiutino i revisori a capire meglio la patch
  6. richiedi la code review su GitHub di almeno uno tra i maintaner del componente e attendi eventuali commenti: affinchè il codice possa essere integrato è richiesta l'approvazione di almeno uno dei revisori
  7. scrivi unit test per le funzionalità introdotte e assicurati che tutti i test passino
  8. quando hai terminato il lavoro e il codice è pronto per essere integrato, rimuovi il marcatore WIP
  9. effettua un rebase dei commit assicurandoti di incorporare le ultime modifiche sul master
  10. assicurati che il numero dei commit all'interno della PR non sia eccessivo e che ogni commit abbia una messaggio significativo
  11. controlla eventuali messaggi (warning) provenienti da DangerJS o da uno dei tool di monitoraggio della coverage e della qualità del software
  12. una volta incorporate le richieste di modifica da parte dei revisori, aspetta l'approvazione di almeno uno di loro (o risolvi eventuali altri richieste)
  13. la PR viene approvata ed integrata nel codice

Buone pratiche per le PR

  1. una PR corrisponde a una e una sola storia su Pivotal
  2. una PR implementa un'unica feature (o chore)
  3. se i primi due punti sono difficili da ottenere, considera di aggiungere storie e ripianificarle
  4. la probabilità che una PR venga rigettata è direttamente proporzionale alla complessità e lunghezza del codice che contiene
  5. quando effettui una PR scrivi una descrizione che aiuti i reviewer a tener traccia di tutti i cambiamenti
  6. aggiungi sempre dei commenti inline a tutto il codice che non è auto-esplicativo

Code review

Se devi effettuare una review puoi far riferimento ai principi espressi in
https://blog.digitalocean.com/how-to-conduct-effective-code-reviews/

Ad esempio:

If you're nitpicking, explain your reasons for doing so. On our team, we often preface nit-picky comments with (nit)

Build automatiche

I processi di monitoraggio della qualità del codice, della coverage e delle PR sono eseguiti tramite la piattaforma CircleCI nell'account del Team Digitale. Ogni progetto contiene la configurazione delle build automatiche in una directory .circleci.

I processi vengono eseguiti automaticamente per ogni Pull Request (e successive push del codice sullo stesso branch) solo se queste provengono da branch appartenenti al repository principale dei progetti. Ciò significa che i tool di monitoraggio non vengono eseguiti in caso di PR provenienti da fork del repository.

Per i controlli automatici delle "best practice" da seguire durante le PR utilizziamo DangerJS.

Assicurati di controllare il report prodotto da DangerJS e seguirne gli eventuali suggerimenti prima di chiudere una issue.

Maintainer

Se hai domande su uno specifico componente puoi contattare i maintainer su Slack o menzionarli nelle issue su Pivotal Tracker (riceveranno una notifica automatica).

Trovi l'elenco dei maintainer nel file AUTHORS.md contenuto nei repository di ogni progetto.

Letture e riferimenti