L'obiettivo è dare alcune indicazioni su come poter lavorare con la nuova Developer platform di Santagostino.
A questo link trovate invece una OTTIMA StyleGuide per la scrittura codice (prendete spunto, al Santagostion lo facciamo!)
Daremo delle linee guida su:
- flusso di lavoro
- scrittura di commit e documentazione
GitHub è il nostro punto d'inizio per tutti gli sviluppi.
Perchè L'abbiamo scelto?
- E' ben integrato con Backstage (lo strumento che abbiamo usato per creare endpoint principale per il catalogo servizi e per i nostri starterkit)
- Le GitHub Actions sono strumento potente per le pipeline di CI/CD
- Ecosistema di servizi molto avanzata (Pages, Project, ...)
Consigliamo l'utilizzo delle PullRequest per strutturare meglio i rilasci e per avere un doppio check del codice
Consigliamo l'utilizzo dei test per migliorare la stabilità del codice per quelle parti "critiche" del codice.
Alcune note sulle PR
- tutte le PR (feature branch > stage / stage >master) devono usare l'opzione di github "create a merge commit" quando vengono approvate
- se i feature branch contengono più di un commit si può selezionare l'opzione squash and merge
- per le PR stage -> master non si deve mai usare l'opzione "squash and merge"
Indicazioni di stile
- Per ogni lavoro creiamo un branch (non lavoriamo sui branch master e stage!) usando questa sintassi
<feature|bug|fixed|>/[<numero_card>_]<nome_branch>(esempiofeature/42_scopo_della_vita) - Ogni pull request dovrà contenere un eventuale riferimento alla card e il titolo della stessa.
Utilizzare questa sintassi
[ref #<numero_card> :] <titolo> - Ogni commit di sviluppo dovrebbe contenere il riferimento per la card di sviluppo
Dotenv-vault è lo strumento che utilizziamo per la condivisione e il monitoraggio degli envfile. Gli envfile sono spesso necessari nella fase di start di un progetto e provvedono a fornire i valori per le variabili d'ambiente relative al progetto stesso. Tuttavia gli envfile contengono spesso dati sensibili ed è quindi necessario aggiungere un layer di sicurezza alla condivisone di tali informazioni.
Perchè l'abbiamo scelto?
- Ci aiuta a garantire gli standard di sicurezza ad un costo operativo minimo.
- Facilita il lavoro di team, è difatti possibile gestire gli accessi ai singoli "spazi di lavoro", detti "Vault", tramite Dotenv-vault
Nel suo ciclo di vita un Vault deve essere inizializzato una sola volta(Idealmente in fase di inizializzazione del progetto) e aggiornato ogni qualvolta gli envfiles subiscano dei cambiamenti. Vediamo di seguito come è possibile effettuare il primo setup ed utilizzarlo.
Se non è ancora stato installato, il primo comando di dotenv-vault su npx lo installerà per noi.
Per inizializzare un vault è necessario aprire la command line e digitare:
npx dotenv-vault new
Questo ci permette di configurare il vault per la prima volta e genera 2 file:
- .env.me, è un file di identificazione utente, non deve essere mai tracciato all'interno delle repository
- .env.vault, è un file che indica su quale vault si opera, va tracciato nei cambiamenti della repository.
Una volta inizializzato il vault è possibile effettuare l'update delle proprietà dell'envfile e/o recuperare la versione più recente dell'envfile. Da riga di comando:
make pull-dotenvesegue lo storage delle modifiche dell'envfilemake push-dotenvrecupera la versione piu' recente dell'envfile dal vault
N.B: make pull-dotenv e make push-dotenv sono rispettivamente i wrapper dei comandi npx dotenv-vault pull e npx dotenv-vault push. Tuttavia per coerenza con gli standard è preferibile utilizzare i wrapper.
Per compiere le azioni pull e push è necessario essere autenticati.
Qualora ci fosse bisogno di autenticarsi è sufficiente digitare da riga di comando:
npx dotenv-vault login
Si aprirà una scheda del browser dove è possibile effettuare la login.
E' possibile gestire gli accessi al vault e controllarne i contenuti.
Da riga di comando è sufficiente digitare:
npx dotenv-vault open
Si aprirà una scheda del browser dove è possibile controllare il nostro vault.
Di seguito disegnamo un flusso di sviluppo che è stato implmentato in tutti gli starterkit e che consigliamo anche per progetti che non partono dagli starterkit.
Da Backstage è possibile "istanziare" un nuovo servizio partendo dallo starterkit che soddisfa i requisiti base.
- Entrare su backstage
- Scegliere lo starterkit desiderato
- Compilare gli step di creazione
- Lanciare lo script di creazione/deploy
- Clonare il repository che è stato "istanziato" da backstage
- Lanciare il comando
make init - Creare branch con il comando
make create-branch-feature BRANCH=<nome-brnach>omake create-branch-fix BRANCH=<nome-brnach>per lo sviluppo (usare le linee guida descritte sopra)
- Se non esiste ancora create il branch di sviluppo (usare le linee guida descritte sopra)
- Sviluppare e fare i commit con un messaggio sempre riferito alla card (se esiste)
- Pusshare in remote il branch (anche per un backup)
- Per chiudere il progetto (se si deve passare ad un'altro) usare
make stopoppuredocker-compose stopper stoppare il docker
NOTA: usare docker-compose start per attivare i container del progetto già inizializzati e buildati.
- Aggiornare la docs
- NON fare mai il merge su stage, creare una pullrequest indicando un reviewer tra quelli del team
- Tenere d'occhio la review per modifiche sul codice o altre segnalazioni
- Alla chiusura della PR fare sempre **create a merge commit" (questo permette a github di non mostrare delle diff sbagliate)
- Aggiornare la docs
- NON fare mai il merge su stage, creare una pullrequest indicando un reviewer tra quelli del team
- Tenere d'occhio la review per modifiche sul codice o altre segnalazioni
- Alla chiusura della PR fare sempre **create a merge commit" (questo permette a github di non mostrare delle diff sbagliate)
NON DIMENTICARE MAI DI FARE GLI UNIT-TEST DEL TUO CODICE, AIUTERANNO LA MANTENIBILITA' E LA COOPERAZIONE TRA I DEV!!!
Abbiamo creato alcuni starterkit che coprono una buona parte delle possibilità di servizi che possiamo creare.
Uno starterkit è la base di sviluppo che già fornisce alcune funzionalità per aiutare il programmatore e per farlo concentrare sulla business logic, accellerando i tempi di sviluppo (non deve gestire, se non in casi particolari, il deploy e la configurazione del progetto).
Uno starterkit racchiude:
- script di deploy
- script di sviluppo
- script per la generazione della docs
- scheletro di infrastruttura
- script per IaC
- readme interno
- configurazione dei test
- configurazione e docs sul sistema di log
- docs per l'utilizzo
Questo file contiene una serie di script che possono essere utilizati per alcune operazioni.
Aiuta a creare "alias" di comandi.
I comandi che troverete saranno:
make init: inizializza il progetto e il branch stagemake all: eseguirà una serire di comandi per inizializzare il progettomake up: accende i docker per il progettomake cli: attiva la shell del container dockermake logs: essendo in docker attivati in detaxch mode questo comando attiva il tail sui logsmake unit-test: lancia la suite di testmake lint: lancia il lintmake stage-deploy: istnaza le librerie necessari per lo sviluppomake build: istanzia i docker necessarimake check-env-file: verifica la presenza del env filemake pull-dotenv: scarica il dotenv dal vaultmake push-dotenv: mette il dotenv nel vaultmake create-branch-feature BRANCH=<nome-brnach>: crea un branch partendo da stage e aumenta di una minor version il package.jsonmake create-branch-fix BRANCH=<nome-brnach>: crea un branch partendo da stage e aumenta di una patch version il package.json
Indipendentemente dal linguaggio (JS o PHP), per instalalre delel dipendenze, dovete sempre entrare nei container e da li lanciare i comandi. In questo modo non si crea incongruenza con i lockfile dei gestori di pacchetti e non darà errore in prod o stage.
La documentazione (se si parte dagli starterkit) verrà deployata in automatico, si dovrà solo scriverla, perchè non partira dai commenti nel codice
Verrà deployata su backstage in modo tale che sarà disponibile nel catalogo servizi.
La docs usa anche PLANTUML un ottimo plugin per fare grafici in markdown e utile per avere una documentaizone più strututrata e di facile lettura.
Come creare una nuova pagina nelal docs?
- Editare il file
mkdocs.ymlaggiungendo la voce di menu desiderata e il path del file MD desiderato - Creare ed editare il fiel di pagina in
/docs/
Se il servizio avrà delle API che potranno essere consumate all'esterno, è bene predisporre anche il file swagger per la documentazione delle API.
Anche questo file verrà letto e gestito da backstage per la generazione della documentazione, nell'apposita sezione API.
Come creare la documentazione per le api?
- creare la cartella
api-docsnella folder principale del progetto. - creare il file
<nome-servizio>_api.yml - usare come template questo file swagger backstage template
- inserire nella parte
definitionlo swagger del servizio
I dati per accedere ai servizi (database, token API, chiavi JWT) sono dati molto sensibili, e averli in chiaro su un repository, potrebbero minarne la sicurezza.
Si è scelto di utilizzare le secrets di GitHub per conservare questi dati e passarli sempre come variabili nei workflow e negli ambienti di stage/prod.
L'organizzazione ha già molte chiavi di default che possono essere utilizzate, in più ogni repository può avere le sue personali.
Localmente : Utilizzare il file .env (nel repository è commentato e deve essere creato come il file .env.template)
Per ambienti di stage e prod
- riportare le variabili su
docker-compose.yml - riportare le variabili sulle gitHub actions
prod.ymlstage.ymlnella sezione env
Come utilizzarli
- localmente
- lanciare il comando
make init
- lanciare il comando
- deploy in stage/prod
- andare su GitHub e a livello di progetto o di organizzazione settare una secrets apposita (Settings > Secrets)
Best practice #1: se la secrets sarà usata da più servizi allora è bene metterla a livello di organizzazione.
Best practice #2: per uniformare l'utilizzo delle secrets è bene utilizzare nomi generali sul progetto (senz aindicare ambinete di STAGE o PROD) cosi che solo nei workflow si vanno a settare le secrets corrette per i vari ambienti su cui si sta facendo il deploy.
Consigliamo di utilizzare il plugin di VSCode REST API perchè permette di avere dei file testuali all'interno del git (opportunamente formattati) per fare chiamate REST.
Il vantaggio sarà quello di condividere tramite GIT le nostre chiamate e di averne alcune di test utili per debug.
NOTA #1: utilizzare estensione .http per avere identazione, colorazione e autocompletamento
NOTA #2: se le nostre API da testare utilizzano delle APIKEY sfruttare i file .env per inserire la chiave cosi rimarrà locale e non sarà pushata su git.
Un progetto di sviluppo (grande o piccolo che sia) per noi è considerato finito quando:
- DoD tecnica passata
- DoD di progetto è passata
- Pipelien di QA sono passate
- Test di UAT sono passati
Per DoD Tecnica definiamo quei punti che devono essere fatti sul progetto su cui si è lavorato (che sia un servizio nuovo o esistente).
Qui sotto elenchiamo i punti che un DEV dovrebbe sempr efare in un progetto:
- implementare/aggiornare test del codice
- implementare/aggiornare swagger (usando sia fastify-swagger per progetti nodejs, o a mano)
- implementare/aggiornare docs di flusso
- aggiornare i packages se obsoleti o se identificati come alert di sicurezza da Dependbot di github (o simili)
- avere nel git chiamate di test delel varie rotti (se necessarie) per poter permettere ad altri dev di mantenere il codice
- implementare codice sempre con un'occhio a:
- sicurezza
- non creare dipendenza tra servizi e passare sempr edal middleware
- non rendere un servizio troppo grosso
- passare dal Cheif software architect per validare l'architettura Software e tecnologia da usare
- usare la coverage del codice per capire se devono essere coperte alcune aree del codice dai test (non è necessario avere una copertura al 100%, ma aver coperto quei punti più critici soprattuo quei punti che potrebbero subire molte modifiche)
- quando si implementa un codice nuovo rispettare la struttura degli starterkit e le regole delal styleguide
Alcuni strumenti che consigliamo per gestire al meglio un progetto
- ClickUP: piattaforma per gestire TASK sfruttando le potenzialità di TRELLO e delle metodologie Kanban, Scrum
- VSCode: Editor molto leggero e customizzabile
- Docker: Ottimo strumento per sviluppare, senza dover configurare ogni volta il proprio pc. Ci permette anche di essere cross-platform a costo zero
- DBeaver: piattaforma open-source per collegarsi a moltissimi tipi di database
- Postman: client per REST API
- Miro: per la creazione di schemi e mappe concettuali collaborative
- Auto close Tag
- Auto complete Tag
- Auto rename Tag
- Babel ES6/ES7
- Beautify
- Better comment
- Code spell check
- Italian code spell check
- Color picker
- CSS peek
- DOT Env
- Editor config
- ESLint
- GIT Graph
- HTML CSS Support
- Indent rainbow
- Live Server
- Local history
- Markdown all-in-one
- Markdown Preview
- Markdown Lint
- Path intellisense
- PHP cs fixer
- PHP Debug
- PHP Extension pack
- PHP Formatter
- PHP Intelephense
- PHP Namespace resolver
- Prettier
- Remote SSH
- Thunder client (es postman)
- SFTP
- Terminal
- Settings sync
- TODO highlight
- XML Tools