Update the contributing documentation

CONTRIBUTING.md

 Ciao, e grazie per il tuo interessamento su come migliorare il sito web di
 Ubuntu-it :-)
 
-
 ## Come contribuire
 
 Il Gruppo Web è composto dai contributori occasionali e dal core team. Fanno
@@ -10,14 +9,6 @@ partecipare alle attività del team. Chi fa parte del core team ha la membership
 del gruppo ubuntu-it-www su Launchpad, come segno di riconoscimento. La
 membership ha rinnovo semestrale.
 
-
-### Cosa c'è da fare
-
-Non c'è bisogno di essere sviluppatori per aiutarci :-) Basta avere voglia di
-fare e di imparare. Di seguito scriviamo le tre maggiori aree di contributo, ma
-se pensi che le tue abilità possano servirci e vuoi aiutarci, scrivici!
-
-
 ### Prerequisiti
 
 - Creazione di un account Launchpad
@@ -25,147 +16,10 @@ se pensi che le tue abilità possano servirci e vuoi aiutarci, scrivici!
 - Firma del codice di condotta
 - Conoscere l'inglese, almeno a livello basilare
 
+### Documentazione
 
-### Design
-
-Hai qualche suggerimento su come migliorare il tema, o vuoi creare immagini da
-mettere sul sito, ma non sai programmare? Non c'è problema, scrivici i tuoi
-suggerimenti, ci penseremo noi a trasformarli in realtà ;-)
-
-Per iniziare, iscriviti alla nostra [mailing list][ml] e presentati, linkando il
-tuo account Launchpad e spiegando cosa vuoi fare!
-
-
-### Contenuti
-
-Ti piace scrivere? Sai creare contenuti che attirano e sorprendono? Vienici a
-trovare! Il sito web è in continua espansione, e aggiungiamo sempre nuove pagine
-con i nuovi fantastici contenuti della comunità e di Ubuntu stesso.
-
-
-### Sviluppatori
-
-Il sito è un sito statico, generato da Python grazie a Flask - non conosci
-queste tecnologie? Non preoccuparti, basta sapere un po' di HTML e un po' di CSS
-per poter aiutarci a scrivere il codice!
-
-Il tema è basato sull'[Ubuntu Vanilla Theme][vanilla] sviluppato da Canonical,
-con alcune modifiche apportate da noi.
-
-Non conosci niente di tutto questo ma vuoi imparare? Sei il benvenuto, questo è
-un team dove si impara tutti insieme :-)
-
-Per iniziare, puoi installare il sito e il tema in locale e iniziare a guardare
-i bug presenti su questo sito
-
-Nel frattempo, iscriviti alla nostra [mailing list][ml] e presentati, linkando
-il tuo account Launchpad, ti forniremo un account su code.ubuntu-it.org, dove è
-ospitato il nostro codice.
-
-Il server di test è ospitato a questo indirizzo:
-[http://wwwtest.ubuntu-it.org][test]
-
-Fai anche un salto su [#ubuntu-it-web su Freenode][irc] per conoscerci, così
-parliamo di cosa c'è bisogno di fare. Come avrai notato, il lavoro è tanto ;-)
-
-
-## Istruzioni per gli sviluppatori
-
-Innanzitutto, ricordati che devi configurare git per poter lavorare con questo
-sito, così come spiegato [qua][git].
-
-
-### Git workflow
-
-Una cosa importante: per ogni contributo (un bug fix, una nuova feature), crea
-un nuovo branch partendo da `master`. Per ovvie ragioni non puoi pushare
-direttamente in master, ma dovrai fare una `Merge Request` e aspettare che
-qualcuno del team faccia una review.
-
-Controlla quindi di essere nel master, avere il codice aggiornato, e crea il tuo
-branch:
-
-```
-git checkout master
-git pull
-git checkout -b ilMioNuovoContributo
-```
-
-E ricordati di aggiungere il tuo nome al file AUTHORS.md ;-)
-
-### Preparare l'ambiente per lo sviluppo
-
-*Testato su Ubuntu 14.04*
-
-Per preparare l'ambiente di sviluppo è necessario disporre di Python 3,
-[virtualenv][2], [pyinvoke][3] e nodejs.
-
-```
-pip install invoke
-```
-
-Dopo averli installati si può generarlo con il seguente comando:
-
-```
-invoke devel
-```
-
-Esso scaricherà tutte le dipendenze da internet (la prima volta), compilerà gli
-assets e creerà un virtualenv con dentro installato il sito (in modalità
-modificabile). Per attivare il virtualenv, bisogna dare in ogni sessione di
-terminale il seguente comando:
-
-```
-source build/envs/devel/bin/activate
-```
-
-Se si modificano gli assets è necessario ricompilarli. Lo si può effettuare con
-il seguente comando:
-
-```
-invoke assets
-```
-
-In caso si facciano modifiche frequenti, può risultare conveniente l'aggiunta
-della flag `-w` al comando, che ricompila gli assets quando sono rilevate
-modifiche.
-
-### Esecuzione del sito in locale
-
-Per eseguire il sito in locale, è possibile eseguire questo comando (una volta
-dentro il virtualenv o con il sito installato globalmente):
-
-```
-uitwww run -d -p 8000 data/
-```
-
-Esso avvierà un'istanza in debug-mode (*da non eseguire in produzione!!!*), che
-ascolta su [localhost:8000][localhost], usando `data/` come directory in cui
-salvare i file necessari al suo funzionamento.
-
-## Generazione di una build
-
-Per creare una build dell'intero sito, è necessario disporre di Python 3,
-[virtualenv][2], [pyinvoke][3] e nodejs. Dopo averli installati si può crearla
-con il seguente comando:
-
-```
-$ invoke build
-```
-
-Esso scaricherà tutte le dipendenze da internet (la prima volta), compilerà gli
-assets e genererà il pacchetto, salvandolo in ``build/packages``. È possibile
-rimuovere tutti i file creati dal processo con il comando:
-
-```
-$ invoke clean
-```
+Ecco la documentazione disponibile:
 
-[2]: https://virtualenv.pypa.io
-[3]: http://www.pyinvoke.org
-[git]: http://code.ubuntu-it.org/ubuntu-it-web/www/wikis/git-setup
-[ml]: http://liste.ubuntu-it.org/cgi-bin/mailman/listinfo/gruppo-web
-[irc]: http://chat.ubuntu-it.org/#ubuntu-it-web
-[vanilla]: https://github.com/ubuntudesign/ubuntu-vanilla-theme
-[test]: http://wwwtest.ubuntu-it.org
-[localhost]: http://localhost:8000
+* [Cosa c'è da fare](docs/cosa-fare.md)
+* [Preparazione dell'ambiente di sviluppo](docs/ambiente-di-sviluppo.md)
+* [Lavorare sul sito](docs/lavorare-sul-sito.md)

docs/ambiente-di-sviluppo.md

+## Preparazione dell'ambiente di sviluppo
+
+Questa è una guida veloce su come installare un ambiente di sviluppo in locale.
+
+Se sei nuovo, ricordati di presentarti in mailing list e richiedere un account
+sull'istanza GitLab!
+
+### Installazione delle dipendenze per lo sviluppo su Ubuntu 16.04 o successivi
+
+È possibile installare tutte le dipendenze richieste dal sito web con il
+seguente comando, prendendole dai repository di Ubuntu. È necessario avere
+Ubuntu 16.04 o superiori installato.
+
+```
+$ sudo apt install git python3 python3-pip python3-virtualenv python3-invoke nodejs nodejs-legacy npm
+```
+
+Inoltre, è necessario installare `yarn` tramite NPM:
+
+```
+$ sudo npm install -g yarn
+```
+
+### Installazione delle dipendenze per lo sviluppo su Ubuntu 14.04
+
+Se si ha Ubuntu 14.04, è necessario installare alcune dipendenze fuori dai
+repository: `invoke` e `nodejs`. Per prima cosa si installano le dipendenze
+presenti:
+
+```
+$ sudo apt install git python3 python3-pip python3-virtualenv
+```
+
+Poi è possibile installare Invoke da PIP:
+
+```
+$ sudo python3 -m pip install invoke
+```
+
+È necessario anche installare Nodejs 4:
+
+```
+$ apt-key adv --keyserver keyserver.ubuntu.com --recv 68576280
+$ apt-add-repository 'deb https://deb.nodesource.com/node_4.x trusty main'
+$ apt update
+$ apt install nodejs
+```
+
+Ed infine, installare `yarn`:
+
+```
+$ sudo npm install -g yarn
+```
+
+### Creare l'ambiente di sviluppo
+
+Dopo aver installato tutte le dipendenze, è possibile clonare il repository con
+il sorgente del sito:
+
+```
+$ git clone http://code.ubuntu-it.org/ubuntu-it-web/www.git
+$ cd www
+```
+
+Dopo, è necessario eseguire Invoke per creare l'ambiente di sviluppo:
+
+```
+$ invoke devel
+```
+
+Invoke scaricherà tutte le dipendenze aggiuntive necessarie (isolandole nella
+directory del sorgente) e creerà l'ambiente virtuale in `build/envs/devel`. Per
+attivarlo, bisognerà dare il seguente comando ogni volta che si apre il
+terminale (da dentro la directory):
+
+```
+$ source build/envs/devel/bin/activate
+```

docs/cosa-fare.md

+## Cosa c'è da fare
+
+Non c'è bisogno di essere sviluppatori per aiutarci :-) Basta avere voglia di
+fare e di imparare. Di seguito scriviamo le tre maggiori aree di contributo, ma
+se pensi che le tue abilità possano servirci e vuoi aiutarci, scrivici!
+
+### Design
+
+Hai qualche suggerimento su come migliorare il tema, o vuoi creare immagini da
+mettere sul sito, ma non sai programmare? Non c'è problema, scrivici i tuoi
+suggerimenti, ci penseremo noi a trasformarli in realtà ;-)
+
+Per iniziare, iscriviti alla nostra [mailing list][ml] e presentati, linkando il
+tuo account Launchpad e spiegando cosa vuoi fare!
+
+### Contenuti
+
+Ti piace scrivere? Sai creare contenuti che attirano e sorprendono? Vienici a
+trovare! Il sito web è in continua espansione, e aggiungiamo sempre nuove pagine
+con i nuovi fantastici contenuti della comunità e di Ubuntu stesso.
+
+### Sviluppatori
+
+Il sito è un sito statico, generato da Python grazie a Flask - non conosci
+queste tecnologie? Non preoccuparti, basta sapere un po' di HTML e un po' di CSS
+per poter aiutarci a scrivere il codice!
+
+Il tema è basato sul [Vanilla Framework][vanilla] sviluppato da Canonical,
+con alcune modifiche apportate da noi.
+
+Non conosci niente di tutto questo ma vuoi imparare? Sei il benvenuto, questo è
+un team dove si impara tutti insieme :-)
+
+Per iniziare, puoi installare il sito e il tema in locale e iniziare a guardare
+i bug presenti su questo sito
+
+Nel frattempo, iscriviti alla nostra [mailing list][ml] e presentati, linkando
+il tuo account Launchpad, ti forniremo un account su code.ubuntu-it.org, dove è
+ospitato il nostro codice.
+
+Il server di test è ospitato a questo indirizzo:
+[http://wwwtest.ubuntu-it.org](http://wwwtest.ubuntu-it.org)
+
+Fai anche un salto su [#ubuntu-it-web su Freenode][irc] per conoscerci, così
+parliamo di cosa c'è bisogno di fare. Come avrai notato, il lavoro è tanto ;-)
+
+[ml]: http://liste.ubuntu-it.org/cgi-bin/mailman/listinfo/gruppo-web
+[irc]: http://chat.ubuntu-it.org/#ubuntu-it-web
+[vanilla]: https://vanillaframework.io

docs/lavorare-sul-sito.md

+## Lavorare sul sito
+
+Questa guida contiene una veloce panoramica all'architettura del sito, e come
+iniziare a lavorare.
+
+Assicurati di aver [l'ambiente di sviluppo](docs/ambiente-di-sviluppo.md)
+preparato sulla tua macchina, e di essere entrato nel virtualenv.
+
+### Panoramica dell'architettura del sito
+
+Il sito è un'applicazione in Python 3, scritta utilizzando il framework
+[Flask][flask]. Per poter sopportare più facilmente i picchi di traffico a cui
+è sottoposto il nostro sito, genera una cache statica di tutte le pagine che lo
+consentono, istruendo nginx di servire quelle al posto di renderizzare la
+pagina da zero.
+
+Per il frontend, utiliziamo SCSS come preprocessore per gli stili, ed il
+[Vanilla Framework][vanilla] di Canonical con [il nostro tema][vanilla-theme]
+applicato sopra.
+
+Questa è la struttura del repository:
+
+* `docs/` contiene la documentazione sul sito
+* `assets/` contiene gli assets del sito (stili, script ed immagini)
+* `uitwww/` contiene il codice Python che fa funzionare il sito
+* `uitwww/navbar.json` contiene la struttura del menu
+* `uitwww/templates` contiene i template (l'HTML) del sito
+* `uitwww/templates/pages` contiene le pagine statiche del sito
+
+### Git workflow
+
+Una cosa importante: per ogni contributo (un bug fix, una nuova feature), crea
+un nuovo branch partendo da `develop`. Per ovvie ragioni non puoi pushare
+direttamente in master, ma dovrai fare una `Merge Request` e aspettare che
+qualcuno del team faccia una review.
+
+Controlla quindi di essere nel master, avere il codice aggiornato, e crea il
+tuo branch:
+
+```
+git checkout develop
+git pull
+git checkout -b il-mio-nuovo-contributo
+```
+
+E ricordati di aggiungere il tuo nome al file AUTHORS.md ;-)
+
+### Esecuzione del sito in locale
+
+Il sito è ora installato in locale! Per avviarlo basta dare il comando (dopo
+aver attivato l'ambiente virtuale):
+
+```
+$ uitwww run data -d
+```
+
+Questo avvierà il sito in locale, in debug mode (**NON IN PRODUZIONE!** - la
+flag `-d`) utilizzando `data/` come directory dove salvare i dati necessari al
+funzionamento del sito (per esempio le varie cache).
+
+### Creazione di una build
+
+Per creare una build del sito in formato `.whl` (pacchetti di Python), basta
+eseguire il seguente comando:
+
+```
+$ invoke build
+```
+
+La build si troverà in `build/packages`.
+
+### Creazione di una nuova pagina
+
+Per creare una nuova pagina, bisogna creare un nuovo template Jinja all'interno
+della directory `uitwww/templates/pages` chiamato come l'URL della pagina. È
+poi necessario riavviare l'applicazione dopo che la pagina è stata creata per
+poterla vedere.
+
+Se per esempio si vuole creare la pagina `sezione/pagina`, è necessario creare
+il file `uitwww/templates/pages/sezione/pagina.html`. Questo è il contenuto di
+base da cui partire:
+
+```
+{# Source code of the Ubuntu-it website
+ # Copyright (C) ANNO  NOME COGNOME <EMAIL>
+ #
+ # This program is free software: you can redistribute it and/or modify
+ # it under the terms of the GNU Affero General Public License as published
+ # by the Free Software Foundation, either version 3 of the License, or
+ # (at your option) any later version.
+ #
+ # This program is distributed in the hope that it will be useful,
+ # but WITHOUT ANY WARRANTY; witout even the implied warranty of
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ # GNU Affero General Public License for more details.
+ #
+ # You should have received a copy of the GNU Affero General Public License
+ # along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ #}
+
+{% extends "layout.html" %}
+
+{% block title %}TITOLO PAGINA{% endblock %}
+
+{% block content %}
+    CONTENUTO HTML
+{% endblock %}
+```
+
+Bisogna inserire poi al posto delle parole in maiuscolo il contenuto.
+
+### Lavorare sugli assets
+
+Essendo scritti in SCSS, gli assets vanno compilati dopo ogni modifica:
+
+```
+$ invoke assets
+```
+
+Per evitare di eseguire ogni volta il comando, si può passare la flag `-w` che
+lo esegue ogni volta che viene rilevata una modifica:
+
+```
+$ invoke assets -w
+```
+
+[flask]: https://www.palletsproject.com/p/flask
+[vanilla]: https://vanillaframework.io
+[vanilla-theme]: http://code.ubuntu-it.org/ubuntu-it-web/ubuntuit-vanilla-theme