| layout | title | permalink | lang |
|---|---|---|---|
page |
Documentazione Tecnica |
/wiki/ |
it |
Benvenuto nel wiki di Covid19Italia, una community basata sui social media, nata per condividere informazioni utili e verificate sul corona virus in Italia.
Il progetto è completamente aperto e chiunque può dare il suo contributo seguendo queste linea guida.
Il nostro sito è creato con Github.
Per essere aggiunto alla lista degli sviluppatori del repository apri un issue qui ed unisciti a questo canale Slack per discutere con noi.
Covid19Italia è un progetto in divenire, per suggerire miglioramenti apri un issue qui. Alla stessa pagina puoi vedere le segnalazioni aperte dagli altri utenti; da lì puoi vedere quello che c'è ancora da fare e da sistemare.
I repository Github che usiamo sono
- QUESTO per lo sviluppo del sito web
- QUESTO per la raccolta e la moderazione delle segnalazioni
- QUESTO per l'archiviazione dei dati aperti da noi prodotti
- QUESTO per lo sviluppo del form di inserimento segnalazioni
- QUESTO per lo sviluppo di una APP mobile
Grazie, aspettiamo il tuo aiuto!
Covid19Italia è un progetto opensource composto da varie applicazioni integrate. Questo WIKI consente di capire come è strutturato il progetto e come poterlo riusare. TerremotoCentroItalia è concesso con licenza Creative Commons Attribuzione 3.0 (CC BY) il cui testo è disponibile a questo indirizzo. Ove non diversamente specificato (ad esempio nei repository del codice sorgente) ti chiediamo se riusi parte del nostro progetto di rispettare i criteri di questa licenza.
- Aprire una Issue
- Come si usa GitHub
- Lavorare sulle Segnalazioni
- Come funziona in breve il metodo TCI
- Convertire un documento Google Docs in Markdown
- Come si inserisce un elemento in Press
- Sviluppare in locale sul sito
Gli Issues possono essere usati per tenere traccia di bug, miglioramenti o altre richieste di progetto.
Tutti gli utenti GitHub possono creare un issue per un progetto di tipo pubblico.
- Su Github naviga fino alla pagina principale del progetto.
- Sotto il nome del progetto fai click sul tab Issue del progetto.
- Fai click sul bottone verde "New Issue"
- Inserisci un titolo e una descrizione per il tuo issue.
Se sei un manutentore del progetto tu puoi assegnare l'issue a qualcuno, associarlo a delle milestone o aggiungere un'etichetta.
Puoi allegare un file trascinandolo nel campo descrizione.
Quando hai fatto fai click su "Submit new issue"
Note: i manutentori del progetto possono
- Creare un template per gli issue in un progetto. I template includono comandi che il manutentore del progetto sceglie di mostrare nella descrizione dell'issue.
- Disabilitare gli issue per un progetto.
Questa pagina è la traduzione di questo semplice tutorial in italiano e descrive i primi passi per iniziare ad usare Github come strumento di progettazione condivisa.
Cosa è Github?
Github è una piattaforma di archiviazione di codice per controllo versione e collaborazione. Ti permette di lavorare assieme agli altri su progetti ovunque.
Questo tutorial ti insegna le cose essenziali per usare Github, come i repository, i branch, i commit e le pull request. Sarai in grado di creare da solo un repository "Ciao Mondo!" ed imparare il flusso di gestione delle pull request, un modo molto popolare di creare e revisionare il codice.
Non è richiesto programmare.
Per completare questo tutorial, hai bisogno di un account Github e un accesso internet. Non hai bisogno di conoscere come programmare, usare la linea di comando o installare GIT (il software per controllare le versioni da riga di comando, integrato in Github).
Trucco: apri questa guida in una pagina del browser separata cosi tu puoi vederla mentre completi i passi del tutorial.
1. Creare un repository
Un repository di solito è usato per organizzare un progetto. I repository possono contenere cartelle e file, immagini, video, fogli di calcolo ed insiemi di dati - ogni cosa che sia necessaria per il tuo progetto. Raccomandiamo di includere sempre un README o un file con informazioni sul progetto. GIthub rende facile crearne uno al momento in cui crei i repository. Ti offre altre opzioni come ad esempio quella di inserire un file di licenza.
Il tuo repository ciao-mondo può essere un posto dove memorizzare idee, risorse o anche condividere e discutere cosa con altri.
Per creare un nuovo repository:
- In alto a destra, dopo aver fatto il login, fai click sul + e poi seleziona New Repository.
- Chiama il tuo repository ciao-mondo.
- Scrivi una breve descrizione.
- Seleziona "Initialize this repository with a README"
- Fai click su "Create Repository"
2. Creare un branch
Fare un branch è un modo di lavorare su più versioni di un progetto alla volta.
Per default il tuo repository ha un branch chiamato master che è considerato essere il branch ultimo. Usiamo i branch per sperimentare e fare modifiche prima di inserirle nel branch master.
Quando fai un branch rispetto al master, stai copiando, o facendo una foto del master cosi come era in quel momento. Se qualcun'altro fa una modifica al master mentre tu stai lavorando sul tuo branch, tu potresti prelevare i suoi aggiornamenti.
Questo diagramma mostra:
- Il branch master
- Un nuovo branch chiamato feature (perchè noi stiamo facendo "feature work" su questo branch)
- Il percorso che feature fa prima che sia fuso con master
Hai mai salvato diverse versioni di un file? Qualcosa tipo:
storia.txt storia-joe-modificata.txt storia-joe-modificata-rivista.txt
I branch facilitano questa cosa nei repository di Github.
Qui, presso Github, i nostri sviluppatori, scrittori e designers usano i branch per tenere traccia delle correzioni dei bug e delle feature separate dal brach di produzione master. Quando una modifica è pronta, la fondono dal loro branch nel master.
Per creare un nuovo branch:
- Vai nel tuo nuovo repository ciao-mondo
- Fai click sul menu in altro sopra la lista dei file dove trovi la dicitura: master
- Scrivi un nome del branch, per esempio "readme-edits", nella casella di testo.
- Seleziona la box Create o premi Enter sulla tastiera
Ora hai due branch. master e readme-edits. Essi sembrano proprio lo stesso ma non lo saranno per molto! Fra poco faremo delle modifiche al nuovo branch.
3. Fai e committa modifiche Bravo! Adesso sei sulla vista del codice per il branch readme-edits, che è una copia del master. Facciamo delle modifiche.
Su Github, le modifiche salvate sono chiamate commit. Ogni commit ha un messaggio associato di commit, che è una descrizione che spiega perchè una particolare modifica è stata fatta. I messaggi di commit tengono traccia della storia delle modifiche, cosi gli altri contributori possono capire cosa hai fatto è perchè.
Fare e committare modifiche:
- Fai click sul file README.md.
- Fai click sull'icona della matita in alto a destra della vista dei file per fare una modifica.
- Nell'editor scrivo un po' di cose su di te.
- Scrivi un messaggio di commit che descrive la tua modifica
- Fai click sul pulsante Commit changes
Queste modifiche saranno fatte al README file solo nel tuo branch readme-edits, cosi che ora questo branch contiene contenuti diversi dal branch master.
4. Aprire una Pull Request
Ottime modifiche! Ora che hai modificato un file in un branch, potrai aprire una pull request.
Le pull request sono il cuore della collaborazione con Github. Quando apri una pull request, proponi le tue modifiche e richiedi che qualcuno le riveda e le "tiri" su e le fonda nel suo branch. Le pull requests mostrano le differenze dei contenuti di entrambi i branch. Le modifiche, aggiunte e le eliminazioni sono mostrate in verde e rosso.
Come fai una commit, puoi aprire una pull request e iniziare una discussione, prima che il codice sia finito.
Usando il sistema di "@" menzioni con Github nel tuo messaggio della pull request, puoi chiedere un feedback da una specifica persona o un team.
Puoi anche aprire pull request nel tuo repository e fonderle da solo. E' un buon modo di imparare il flusso di gestione prima di lavorare su progetti complessi.
Aprire una pull request per una modifica al file README
Fai Click sul tab Pull Request tab, quindi dalla pagina Pull Request, fai click sul bottone verde New pull request.
Seleziona il branch dove hai fatto le modifiche per compararlo con il master.
Guarda le tue modifiche nel diff sulla pagina di Compare, assicurati che sono cosa tu vuoi sottomettere.
Quando tu sarai soddisfatto delle modifiche, fai click sul grande pulsante "Create Pull Request"
Dai alla tua pull request un titolo e scrivi una breve descirzione delle tue modifiche.
Quando hai scritto il tuo messaggio, fai click su Create pull request!
Suggerimento: puoi usare emoji e fare drag and drop di immagini e gif nei commenti.
5. Fondere una Pull Request
In questo step finale, è tempo di portare le tue modifiche fondendole dal tuo branch readme-edits nel branch di produzione master.
- Fai click sul pulsante verde Merge pull request per fondere le modifiche sul branch master
- Fai click su Confirm merge
- Procedi e cancella il branch, dato che le tue modifiche sono state incorporate, con il pulsante "Delete branch" in viola.
Evviva!
Completando questo tutorial, hai imparato a creare un progetto e fare una pull request su Github!
Qui a cosa ti sarà utile questo tutorial:
- Creare un repository opensource
- Iniziare e gestire un nuovo branch
- Modificare un file e committare le modifiche su Github
- Aprire e Fondere una Pull Request
Dai un'occhiata al tuo profilo Github e vedrai un nuovo spazio di contributi!
Per molti altri tutorial su Github consulta questa pagina.
Premessa:
Questo documento è destinato al team che lavora sulle Segnalazioni. Gli altri utenti non hanno i permessi per effettuare le operazioni descritte qui, ma possono liberamente lasciare un commento su qualsiasi Issue contribuendo alla stessa. Ad esempio, a questo link si possono vedere tutte le segnalazioni a cui ancora manca una posizione. Si possono suggerire in un commento le coordinate. Un moderatore la prenderà in carico e applicherà i vostri suggerimenti il prima possibile.
Per entrare a far parte del team di Moderatori, assicurati di essere un membro attivo della community, di aver contribuito precedentemente ed entra nella chat di gruppo dei collaboratori.
Ogni compilazione di un modulo di Covid19Italia genera - dopo circa 30 secondi - una nuova Issue qui.
A queste Issue vengono applicate diverse etichette per descriverne la natura e lo stato di approvazione (che ne determina la pubblicazione finale sul sito, sui bollettini, su Twitter, sui canali e bot Telegram,..).
Questo permette a tutti di poter collaborare alla classificazione, moderazione e verifica comunitaria delle segnalazioni. È disponibile uno storico di tutte le modifiche, operazioni e moderazioni su ogni singola Issue.
Basta un account su GitHub e un browser web, nessuna conoscenza o strumento informatico è richiesto.
Le segnalazioni devono mantenere questa struttura:
<pre><yamldata>
Campo1: Valore del campo1
Campo2: Valore del campo2
</yamldata></pre>
Prestate attenzione alle seguenti convenzioni, quando modificate il contenuto di una Issue:
- I campi che vanno su più righe vanno delimitati da un
'. Esempio:
Descrizione: 'Il contenuto di questo campo
va su più
righe
'
Campo2: Questo campo invece è su una sola riga
Attenzione: I campi su più righe devono essere delimitati da ' (uno all'inizio e uno alla fine del campo). ' è usato per delimitare il contenuto di un campo quindi non può essere usato con la normale funzione di apostrofo all'interno. Per poter usare ' letteralmente, e non come delimitatore, utilizzare \'
Ad esempio, se volessi scrivere l'altro una volta per riga, in un campo multi campo, dovrei fare così:
'
L\'altro
L\'altro
'
' viene utilizzato come delimitatore, mentre viene scritto \ per usarlo letteralmente. Nella segnalazizone finale verrà poi mostrato semplicemente come '.
-
Il titolo dell'Issue diventa il titolo della segnalazione sul sito frontale.
-
Le modifiche (inclusa la pubblicazione/depubblicazione) appaiono sul sito finale dopo massimo 15 minuti. Usate CTRL+F5 oppure la modalità navigazione in anonimo se non vedete cambiamenti. Se dopo queste operazioni ancora le cose non vi tornano procedente ad aprire Issue riportando il problema. Le Issue sui moduli (campi, struttura, dati mancanti) vanno aperte su covid19italia_forms.
-
Se avete bisogno di cambiare le Label che vengono preassegnate alle Issue (quelle che vedete già assegnate automaticamente) segnalatecelo qui
-
Non rimuovete la Label "form", ci aiuta ad investigare l'origine delle segnalazioni.
Ci sono alcune issue che hanno un campo "Posizione", come questa
E finiscono nella mappa che c'è qui
Se la segnalazione non ha una geolocalizzazione, lo script prova da solo a cercare nomi di comuni/città all'interno dei vari campi compilati. Se trova qualcosa, aggiunge da solo la posizione. Quando succede, viene applicata l'etichetta Posizione da verificare e il bot commenterà chiedendovi una conferma, dandovi anche un link a quelle coordinate per vedere subito se hanno senso o no.
Se anche dopo questo tentativo non si trova una posizione, viene applicata l'etichetta Posizione mancante così da poter filtrare tutte quelle che ne hanno ancora bisogno.
Quindi, le issue segnalate con la label Posizione mancante hanno bisogno di un intervento manuale che aggiunga la posizione.
Prendiamo ad esempio questa segnalazione su Milano)
Si può usare questo sito: Nominatim.
In alto a destra c'è un tasto che si chiama "Show map bounds". Quando viene premuto, compare un rettangolo che contiene le coordinate. La riga più importante è "Last click".
Ci sono due numeri, separati da una virgola, sono latitudine e longitudine. Copiateveli.
Adessa, sulla Issue, va cliccato il tasto ... in alto a destra, quindi "edit".
Adesso aggiungete (o modificate) il campo 'Posizione', aggiungendo le coordinate ottenute poco fa:
...
Posizione: 43.768137 11.241812
Il primo valore è la Latitudine, il secondo la Longitudine (obbligatori). Il terzo e il quarto indicano Altitudine e Precisione (metri). Questi ultimi due sono facoltativi.
Esempio:
Guardando sul sito nella pagina www.covid19italia.help/issues/ (ad esempio https://www.covid19italia.help/issues/748/) se la segnalazione ha una posizione già inserita, i valori Provincia e Regione sono quelli riconosciuti in base ai dati geografici. In questo caso, se ci sono errori, sarebbe più utile sistemare la posizione.
Ci possono essere delle segnalazioni che hanno una regione o provincia o un Comune di riferimento, ma per le quali non ha senso inserire una coppia di coordinate. Perché queste segnalazioni vengano comunque elencate nella pagina per regione o per provincia, si può inserire un campo nei dati del tipo
regione_manuale: Veneto
oppure
provincia_manuale: Bologna
oppure
comune_manuale: Cento
(Naturalmente non avendo una posizione la segnalazione non sarà visualizzata in mappa)
NB Attenzione all'ortografia del nome: dev'essere esattamente quello che è utilizzato dalle altre segnalazioni.
<pre><yamldata>
Da_chi_offerta: comitati di quartiere
Descrizione: 'Iniziativa di cittadini e cittadine, comitati ed associazioni del Quartiere
(Centro storico) di Firenze: consegnano cibo e beni primari a chi ne fa richiesta.'
Destinatari: Consegna di cibo e generi di prima necessità
Link: https://google.it
Natura: solidale
Posizione: 43.768137 11.241812
Tipo_di_soggetto: privato
Titolo: Serve aiuto?
</yamldata></pre>
Queste sono alcune delle politiche, linee guida e regole su cui è stato deciso:
- Non accettiamo segnalazioni riguardo ricerca scientifica (emergenzeHack/covid19italia_segnalazioni#315 (comment))
- Se alcuni campi sembrano invalidi, provare a correggerli o cercare maggiori informazioni su Google a partire dal titolo, NON chiudere immediatamente la Issue se non va il link o problemi analoghi.
Per discutere o fornire feedback, aprite un Issue
Questo progetto è "clonato" da un precedente usato per il terremoto del centro italia del 2016 chiamato TCI.
TCI (terremotocentroitalia.info) è un sito "dinamico" basato su:
- una gestione di segnalazioni tramite issue github e da alcuni script (d'ora in poi "backend")
- una catalogazione e impaginazione delle segnalazioni tramite jekyll (d'ora in poi "frontend")
Il backend è direttamente rappresentato da un repo github del quale viene utilizzata solo la parte di segnalazioni (lo potete vedere qui https://github.com/emergenzeHack/terremotocentro_segnalazioni/issues).
Pro:
- il sistema è robusto, funzionale, gestito da altri
- molto facile da usare, ci sono varie persone che hanno già esperienza
- possibilità di aggiungere tag alle segnalazioni per la catalogazione
- API per scaricare
Contro:
- per inserire info "machine readable" nelle segnalazioni usiamo YAML, che dev'essere gestito da un editor esterno
- se lo YAML si rompe, bisogna intervenire "a mano"
Ogni 5 minuti, uno script (https://github.com/emergenzeHack/covid19italia/blob/master/scripts/csvupdate.sh):
- scarica tutte le segnalazioni da github
- decodifica lo YAML
- crea un array JSON che contiene le segnalazioni e lo YAML convertito in JSON
- committa eventuali differenze sul repo GIT, scatenando webhook e nuova build
Siccome Jekyll interpreta direttamente JSON, ci sono varie pagine che filtrano il JSON e creano HTML con liste, mappe, etc
I framework utilizzati sono:
- bootstrap per il layout
- openlayers/leaflet per le mappe
Pro:
- molto veloce da servire
- si può appoggiare su siti esterni come netlify
- praticamente inattaccabile
Contro:
- nei momenti di massimo movimento, l'aggiornamento è ogni 5 minuti
- La trasformazione delle issue nel sito potrebbe essere fatta in modo più efficiente usando gli hook di github e un DB qualsiasi per memorizzare i dati, in modo da poter avere aggiornamenti più rapidi. Resta il fatto che quando il sito è "fermo", non ha senso avere un DB da interrogare ogni momento
Sotto qualche semplice passaggio per convertire un documento fatto in Google Docs in un formato compatibile con questo WIKI o come post del blog di questo sito così da poter continuare ad usare Google Docs se lo si usa normalmente per scrivere e poi pubblicare contenuti su covid19italia.help
- Installare nei Componenti aggiuntivi il plugin "Docs to markdown" (dal menu Componenti Aggiuntivi -> Installa componenti aggiuntivi cercate "Docs to markdown".
- una volta che il documento in Google Doc è pronto aprire il menu Componenti Aggiuntivi selezionate la voce "Docs to Markdown" e poi "Convert"
- Dal pannello a Sinistra premete sul pulsante Markdown.
A questo punto selezionate tutto il testo che viene tradotto sotto...copiatelo con un normale "Copia" : questo è il vostro testo nel linguaggio compatibile con Github!
Andate ad esempio nella sezione WIKI, Create una nuova Pagina dandole un titolo ed incollate il testo. Alla fine salvate la pagina e la troverete pubblicata.
Nota: la guida di come si usa in dettaglio "Docs to markdown" si trova anche qui
Fatto!! Facile no?
Per inserire un elemento nella tabella PRESS procedere come segue:
- Andare su questo file dei PRESS
- Cliccare sull'icona matita per editare il file su Github
- Aggiungere una riga al file ed inserire in sequenza data,fonte,titolo,link separati da virgola. Nota: non devono esserci virgole ulteriori eccetto quelle che separano i 4 campi.
- Cliccare sul pulsante "Commit changes" o "Propose changes" in basso
- Se viene proposto un pulsante verde "Create Pull Request" Premerlo ed attendere che li amministratori validino la modifica.
Fatto.
Questa breve guida ti spiegherà come creare sul tuo computer una copia del sito. In questo modo le modifiche al codice saranno immediatamente visibili nella tua copia locale, e potrai testare tutti i miglioramenti che stai progettando. Cominciamo!
Dovrai installare sul tuo computer alcuni software per lo sviluppo. Nelle pagine linkate trovi tutte le istruzioni in dettaglio.
Per gli step successivi è richiesto un minimo di dimestichezza con il terminale a riga di comando. Niente di speciale, è uno strumento che ci consente di dare comandi al computer sotto forma di testo invece che cliccando con un mouse in una finestra. Gli utenti Mac e Linux dovrebbero avere già l'applicazione Terminale installata; per gli utenti Windows l'installazione di git include già un terminale simile a quello di Linux.
Glisseremo anche su molti dettagli di git e Github, rimandandovi all'altra guida presente nella nostra wiki.
I comandi da inserire nel terminale (anche copia-incollando) saranno indicati in questo modo: comando di esempio
Per prima cosa verifichiamo di avere installato Ruby e bundler, che a sua volta ci aiuterà a installare tutte le dipendenze che ci servono.
Su Mac con Homebrew:
brew install ruby
installa la gem bundle
sudo gem install bundler:1.17.3
installa command line developer tools
xcode-select --install
Su Ubuntu:
sudo apt install build-essential git ruby-full ruby-bundler zlib1g-dev
Facciamo su github il fork del repository, poi cloniamo il nostro fork in locale: git clone https://github.com/nomeutente/covid19italia.git (ricordati di sostituire il tuo vero nome utente)
Se si lavora sui dati (_data/) bisognerà forkare e lavorare su covid19italia_data invece che su covid19italia.
Portiamoci all'interno della nuova cartella: cd covid19italia
Installiamo tutte le dipendenze del progetto: bundle install --path vendor/bundle
Eseguiamo, sempre nella cartella covid19italia, bundle exec jekyll serve
Il programma stamperà a video l'indirizzo da aprire nel browser, che sarà del tipo http://127.0.0.1:4000/.
Ecco fatto, tutto qui! Buon lavoro 💪
Per ottenere una versione statica del sito bisogna eseguire il processo di build.
È lo stesso processo che viene eseguito quando viene rilasciato l'aggiornamento sulla versione pubblica del sito.
Per eseguire la build in locale bisogna eseguire questo comando:
bundle exec jekyll buildPer una rapida installazione di tutti gli strumenti necessari per lo sviluppo del sito è possibile utilizzare docker per creare un ambiente di esecuzione. All'interno del progetto, nella cartella Docker è presente un semplice DockerFile per generare un'immagine mediante la quale è possibile creare dei container da usare per avviare il sito o effeuare una build.
per costruire l'immagine, spostati nella directory "Docker" nella radice del progetto ed esegui:
docker build -t covid_dev .
questo costruirà l'immagine docker con covid_dev come nome tag, ovviamente, puoi cambiare il nome da assegnare all'immagine.
per eseguire un container con l'immagine appena creata, dalla radice del progetto, digita:
docker run --rm -v ${PWD}:/opt -p 4000:4000 --name covid -it covid_dev
dove:
- --rm richiede che il container venga eliminato dopo aver terminato l'esecuzione
- -v $ {PWD}: / opt monta la radice del progetto nella cartella / opt del container
- -p inoltra la porta 4000 della macchina host alla porta 4000 del container
- --name dà un nome al container
- -it permette di avviare il container in una shell interattiva
il container, all'avvio installa le dipendenze ruby nel percorso vendor/bundle ed eseguirà il comando serve: bundle exec jekyll serve
ora sei pronto per iniziare, digita http://127.0.0.1:4000 nel tuo browser per accedere al sito web.
per maggiori informazioni, si rimanda al sito di Docker
Se fate girare il sito su una macchina con Linux e sviluppate sotto Windows dovrete aggiungere -H 0.0.0.0 al comando serve, tipo:
bundle exec jekyll serve -H 0.0.0.0
In questo modo potrete aprire il sito da qualsiasi postazione connessa alla vostra rete e non solo dal localhost. Utile per testare le modifiche con cellulari, tablet o altri browser.