Merge remote-tracking branch 'origin/docs' into dev-shadmod-231013-2030

CONTRIBUTING.md

@@ -13,7 +13,160 @@ Se vuoi aiutarci, consulta la pagina wiki [GruppoWeb/Contribuire](https://wiki.u
 
 ## Documentazione
 
-* [Pagina wiki GruppoWeb/Documentazione](https://wiki.ubuntu-it.org/GruppoWeb/Documentazione)
-* [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)
+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
+- Richiesta di un account su code.ubuntu-it.org
+- Firma del codice di condotta
+- Conoscere l'inglese, almeno a livello basilare
+
+
+### 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
+```
+
+[2]: https://virtualenv.pypa.io
+[3]: http://www.pyinvoke.org
+[git]: http://code.ubuntu-it.org/ubuntu-it-web/www/blob/docs/docs/intro-to-git.md
+[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
+````
\ No newline at end of file

docs/intro-to-git.md

+##Introduzione a git
+Per prima cosa bisogna installare git:
+
+*Debian/Ubuntu*
+```
+sudo apt-get install git
+```
+
+Dopo aver installato git, la prima cosa da fare è impostare username ed email:
+```
+git config --global user.name "Username"
+git config --global user.mail xxxxx@xxx.xxx
+```
+
+Infine dovrai recarti sulla pagina http://code.ubuntu-it.org/profile/keys e aggiungere la tua chiave SSH pubblica.
+
+Ora puoi scaricare il codice del sito. Ricorda che per ogni contributo dovrai creare un nuovo branch partendo da master e successivamente fare una Merge Request:
+```
+git clone git@code.ubuntu-it.org:ubuntu-it-web/www.git
+cd ubuntu-it-web
+git checkout -b nuovoBranch
+```
+
+Per qualsiasi dubbio puoi chiedere sul canale IRC del gruppo web: freenode#ubuntu-it-web