Commit 2b8bb919 authored by Pietro Albini's avatar Pietro Albini

Update the contributing documentation

parent 9ca0233e
Pipeline #38 passed with stage
in 0 seconds
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)
## 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
```
## 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
## 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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment