Grazie per aver deciso di contribuire al progetto!
In questa pagina troverai tutte le informazioni necessarie per poter contribuire al progetto in varie forme.
Per contribuire nella stesura del libro puoi fare una qualsiasi delle seguenti attività.
Se hai un'idea per un capitolo, puoi proporla aprendo una nuova issue.
Github ti proporrà un template per la creazione della issue, che ti suggeriamo di utilizzare.
Inserisci quante più informazioni possibili e specifica se vorresti occuparti interamente della prima stesura o se invece vorresti produrre il contenuto in collaborazione con altri contributori.
Una volta aperta la issue, verrà automaticamente assegnata una label nuovo-capitolo.
A questo punto, un qualsiasi Ambassador potrebbe decidere di assegnare a se stesso la issue. Ti consigliamo di pubblicizzare la tua idea in ogni modalità a te possibile e/o contattare eventuali Ambassador di tua conoscenza per chiedere loro di dare un'occhiata alla tua proposta e valutare la possibilità di assegnare la issue a se stessi.
Nel momento in cui un Ambassador deciderà di assegnare la issue a se stesso, un branch verrà creato in maniera automatica e il lavoro di stesura potrà cominciare.
Prosegui nella lettura di questa pagina alla voce Modalità di stesura di un capitolo per capire come procedere da qui.
Se hai un'idea per migliorare un capitolo esistente, puoi proporla aprendo una nuova issue.
Github ti proporrà un template per la creazione della issue, che ti suggeriamo di utilizzare.
In alternativa, potresti aprire direttamente una Pull Request, ma ti consigliamo di aprire una issue per discutere prima della modifica da apportare e capire se la tua idea è condivisa dalla community.
Bene, hai individuato un capitolo a cui contribuire / da modificare e vuoi cominciare a scrivere dei contenuti. Ma come?
Le modalità di stesura del capitolo sono principalmente due:
-
In accordo con la persona del team Ambassador assegnataria del capitolo di interesse, potrete decidere di mettervi in contatto per lavorare insieme alla stesura del capitolo. In questo caso, potrete decidere di utilizzare un qualsiasi strumento di scrittura collaborativa (Google Docs, Office 365, ecc.) e di caricare il contenuto nel branch una volta terminato. Per comodità, si suggerisce di lasciare alla figura di Ambassador il compito di caricare il contenuto nel repository rimuovendo la necessità di una ulteriore Pull Request.
-
In accordo con la persona del team Ambassador assegnataria del capitolo, potrai stendere in prima battuta il contenuto del capitolo e far sì che la persona assegnataria ti faccia da revisore e guida. In questo caso, sarà necessario fare un fork del branch relativo al capitolo e aprire una Pull Request che dovrà puntare a quello stesso branch come destinazione. Una volta aperta la Pull Request, la persona assegnataria del capitolo potrà iniziare a revisionare il contenuto e a suggerire modifiche.
Una volta terminato il lavoro, la persona assegnataria del capitolo aprirà una Pull Request (o modificherà quella già presente dadraftaready for review) e chiederà una revisione al resto della community. Le regole di approvazione dei contenuti sono regolate dal Governance Group del progetto e sono disponibili qui.
I contenuti del libro sono scritti in formato markdown e sono organizzati in cartelle e file.
Sarà sufficiente avere una qualsiasi versione di Node.js installata sul proprio computer per poter formattare i file markdown in maniera automatica e un qualsiasi IDE per la stesura.
Dopo aver clonato il progetto ed essendosi spostati sul branch relativo al capitolo di interesse, eseguire il comando npm i per installare le librerie.
Tutti i file markdown devono essere formattati con Prettier per una miglior leggibilità e per evitare inutili merge conflict se più persone lavorano allo stesso file.
Per formattare da linea di comando tutti i file è sufficiente lanciare il seguente comando nella cartella del repository:
npm run format:writeFortunatamente i principali IDE supportano Prettier tramite delle estensioni, di seguito alcuni esempi:
Per formattare i file markdown con Visual Studio Code è necessario installare l'estensione Prettier - Code formatter.
Un buon consiglio è tenere attivo il flag Format On Save direttamente nelle impostazioni di vscode per evitare di dover formattare ogni volta a mano.
Per formattare i file markdown con IDE JetBrains è necessario installare l'estensione Prettier, tranne per WebStorm che include già Prettier di default.
Alcuni suggerimenti di configurazione si possono trovare qui.
Per formattare i file markdown con Vim è necessario installare il plugin vim-prettier.
Alcuni suggerimenti di configurazione si possono trovare qui.
Nella documentazione di Prettier sono presenti le istruzioni per configurare il tool nel proprio IDE preferito: Editor Integration.
Per mantenere uno storico e poter costruire dei changelog è richiesto a tutti i contributori del progetto di utilizzare i Conventional Commits.
In pratica è necessario utilizzare dei prefissi per i commit che indicano il tipo di commit e il contesto, ad esempio:
git commit -m "feat: aggiunta nuova pagina"Il libro è, in questo momento, orientato ad un pubblico italiano.
Volendo essere accessibile alla platea più ampia possibile, è necessario utilizzare un linguaggio semplice e chiaro, espresso in lingua italiana, per i contenuti, le cartelle, i commit, le Pull Requests, i commenti, ecc.
Seppur abituati a scrivere in inglese commit e Pull Requests, richiediamo a chi contribuisce di utilizzare la lingua italiana anche in questi casi, al netto del <type> dei commit per seguire i Conventional Commits, che resteranno in inglese.
Per quanto riguarda i capitoli del libro, è stata già predisposta una futura integrazione di ulteriori lingue (traduzioni) utilizzando un approccio language driven per la struttura delle cartelle. Si avrà quindi, ad esempio: docs/it/nome-del-capitolo.md per la lingua italiana, docs/en/name-of-the-chapter.md per l'inglese, e così via.
Note
Il nome del file (nome-del-capitolo.md) rappresenta, a tutti gli effetti, lo slug dell' url. Cercando sempre di mantenere una nomenclatura efficace e concisa (esempio: ✅ sviluppo-mobile e non ❌ capitolo-sulle-metodologie-di-sviluppo-per-applicazioni-mobile), è necessario utilizzare la convenzione di nomenclatura Kebab case (quindi parole in minuscolo separate da un -).
Prima di stendere contenuti o proporre delle Pull Request si suggerisce di dare una lettura alle Linee Guida (E relativo Cheatsheet) da rispettare quando si interagisce con il repository.