Utilizzo di git per lavorare sul sito web Debian

Utilizzo del repository Git

Iniziamo, in questa sezione imparerete come creare una copia locale del repository principale, come mantenere tale repository aggiornato e come inviare il tuo lavoro. Spiegheremo anche come lavorare sulle traduzioni.

Ottenere una copia locale

Come prima cosa, installare Git. Poi, configurare Git e inserire nome e indirizzo email. Se è la prima volta che si utilizza Git, si raccomanda di leggere la documentazione fi Git.

Il passo successivo è clonare il repository (cioè creare la copia locale). È possibile farlo in due modi:

Nota: La clonazione dell'intero repository webwml richiede di scaricare circa 1,3 GB di dati e potrebbe essere problematica per coloro che hanno collegamenti a Internet lenti o instabili. È possibile usare la clonazione superficiale con una profondità iniziale minima per diminuire i dati da scaricare: 

  git clone [email protected]:webmaster-team/webwml.git --depth 1

Una volta ottenuto un repository (superficiale) utilizzabile, è possibile aumentare la profondità della copia locale o eventualmente convertirla in una copia locale completa:

  git fetch --deepen=1000 # aumenta la profondità del repo di altri 1000 commit
  git fetch --unshallow   # recupera tutti i commit mancanti, converte il repo in uno completo

Inoltre è possibile fare il checkout solo di un sottoinsieme di pagine in questo modo:

  1. git clone --no-checkout [email protected]:webmaster-team/webwml.git
  2. cd webwml
  3. git config core.sparseCheckout true
  4. Creare nella directory webwml il file .git/info/sparse-checkout per definire i contenuti di cui fare il checkout. Per esempio per recuperare i soli file di base, le pagine in inglese e le traduzioni in spagnolo e catalano, dovrebbe essere così: 
          /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
  5. Infine fare il checkout del repository: git checkout --

Inviare le modifiche locali

Tenere il repository locale aggiornato

Ogni due o tre giorni (e sicuramente sempre prima di iniziare a lavorare sulle modifiche!) si dovrebbe eseguire

  git pull

per recuperare qualsiasi file dal repository che ha subito modifiche.

È fortemente raccomandato tenere la propria directory di lavoro locale di Git pulita prima di effettuare git pull e le successive modifiche. Se ci sono delle modifiche delle quali ancora non è stato fatto il commit o dei commit locali che non sono presenti nel branch attuale sul server remoto, l'esecuzione di git pull creerà automaticamente dei merge commit oppure potrebbe fallire a causa di conflitti. È consigliabile tenere i propri lavori non completati in un branch differente oppure usare comandi come git stash.

Nota: Git è un sistema per il controllo delle versioni distribuito (non centralizzato), ciò vuol dire che il commit delle proprie modifiche viene memorizzato solo nella propria copia locale. Per condividere le modifiche con gli altri è necessario eseguire anche il push delle proprie modifiche verso il repository centrale su Salsa.

Esempio di come modificare una pagina in inglese

Di seguito un esempio su come modificare dei file che fanno parte del codice sorgente del sito web in inglese del. Dopo aver recuperato una copia locale del repository con git clone e prima di iniziare le modifiche, eseguire questo comando:

  1. git pull
  2. Adesso è possibile modificare i file.
  3. Una volta completato, eseguire il commit delle modifiche sul proprio repository locale con: 
        git add percorso/al/file
    git commit -m "Messaggio di commit"
  4. Se si dispone dell'accesso in scrittura senza limitazioni al repository remoto webwml, è anche possibile fare il push delle modifiche direttamente sul repository su Salsa: git push
  5. Se non si dispone dell'accesso in scrittura al repository webwml, si possono inviare le proprie modifiche tramite una richiesta di unione oppure chiedere aiuto agli altri sviluppatori.

Chiudere bug in Debian con commit su Git

Se nel messaggio di commento di un commit viene inserito Closes: #nnnnnn allora quando verrà fatto il push delle modifiche il bug con numero #nnnnnn verrà chiuso automaticamente. Il formato esatto di questa funzionalità è lo stesso di Debian policy.

Collegamenti tramite HTTP/HTTPS

Molti dei siti web di Debian supportano SSL/TLS, quindi utilizzare collegamenti HTTPS ogni volta che sia possibile e sensato. Tuttavia alcuni siti web Debian/DebConf/SPI/ecc. non supportano HTTPS oppure usano come Certification Autority solo SPI (e non una CA SSL fidata da tutti i browser). Per evitare di inviare messaggi d'errore agli utenti, non inserire collegamenti verso questi siti con HTTPS.

Il repository Git rigetta qualsiasi commit che contiene dei collegamenti con HTTP a siti web Debian che supportano HTTPS o che contiene dei collegamenti HTTPS a siti web di Debian/DebConf/SPI dei quali è noto che non supportano HTTPS o che utilizzano certificati firmati solo da SPI.

Lavorare sulle traduzioni

Le traduzioni devono essere tenute aggiornate con il file in inglese corrispondente. L'intestazione translation-check nei file delle traduzioni è usato per tracciare su quale versione del file inglese è basata la traduzione. Se si cambia il file tradotto, è necessario aggiornare l'intestazione translation-check in modo che corrisponda all'hash del commit git della corrispondente modifica sul file in inglese. È possibile recuperare il valore dell'hash con

  git log percorso/al/file/in/inglese

Per fare una nuova traduzione, usare lo script copypage.pl. Creerà un modello per la propria lingua impostando sulla traduzione la corretta intestazione.

Cambiare le traduzioni con smart_change.pl

smart_change.pl è uno script usato per rendere più semplice fare assieme l'aggiornamento dei file originali e delle loro traduzioni. Può essere utilizzato in due modi, in base ai cambiamenti che si stanno facendo.

Per usare smart_change solo per aggiornare l'intestazione translation-check quando si lavora sui file manualmente:

  1. Cambiare i file originali e fare il commit
  2. Aggiornare le traduzioni
  3. Eseguire smart_change.pl -c COMMIT_HASH (usare l'hash del commit delle modifiche al file originali). Prenderà le modifiche e aggiornerà le intestazioni nei file tradotti
  4. Rivedere le modifiche (per esempio con git diff)
  5. Fare il commit delle modifiche alle traduzioni

Oppure, usare smart_change con una espressione regolare per fare più cambiamenti su più file in un solo passaggio:

  1. Eseguire smart_change.pl -s s/PIPPO/PLUTO/ fileoriginale1 fileoriginale2 ...
  2. Rivedere le modifiche (per esempio con git diff)
  3. Fare il commit dei file originali
  4. Eseguire smart_change.pl fileoriginale1 fileoriginale2 (questa volta senza l'espressione regolare); questo aggiorna le intestazioni nei file delle traduzioni
  5. Infine, fare il commit delle traduzioni modificate

Rispetto al precedente è più complicato, richiede due commit, ma è inevitabile a causa di come git gestisce gli hash dei commit.

Accesso in scrittura al repository Git

L'intero codice sorgente del sito web Debian è gestito con Git, il repository è https://salsa.debian.org/webmaster-team/webwml. Agli ospiti non è permesso di fare il push dei propri commit nel repository con il codice sorgente. Per ottenere l'accesso in scrittura al repository è necessario avere un permesso particolare.

Accesso in scrittura illimitato

Chi necessita dell'accesso in scrittura senza limitazioni (per esempio, si vuol diventare un autore attivo), può chiedere l'accesso in scrittura tramite l'interfaccia web https://salsa.debian.org/webmaster-team/webwml dopo aver fatto il login sulla piattaforma Salsa di Debian.

Se non si conosce come avviene lo sviluppo del sito web Debian e non si hanno esperienze precedenti, si dovrebbe anche inviare una email a [email protected] con una breve introduzione di sé stessi prima di inviare la richiesta di accesso in scrittura. L'introduzione dovrebbe contenere informazioni utili come in quale lingua o su quale parte del sito web si vuole lavorare e chi può fare da garante.

Accesso in scrittura al repository tramite Merge Request

Se non si intende ottenere l'accesso in scrittura senza limitazioni oppure non si è in grado di farlo, è comunque sempre possibile inviare una Merge Request e lasciare che altri sviluppatori rivedano e accettino il vostro lavoro. Inviare le proprie Merge Request usando la procedura standard della piattaforma Salsa GitLab tramite l'interfaccia web e consultare i seguenti documenti:

Le Merge Request non sono controllate da tutti gli sviluppatori del sito web e non sempre sono lavorate in tempo. Se non si è sicuri che il vostro contributo sia accettato, inviare una email alla lista di messaggi debian-www e chiedere la revisione.

Recezione di notifiche

Se si sta lavorando sul sito Debian, probabilmente si vuole sapere cosa sta succedendo nel repository webwml. Ci sono due modi per rimanere aggiornati: ricevere notifiche di commit e ricevere notifiche di richiesta di unione.

Recezione di notifiche di commit

Il progetto webwml su Salsa è stato configurato in modo che i commit sono mostrati nel canale IRC #debian-www.

Chi vuole, può ricevere delle notifiche via email quando avvengono dei commit nel repository webwml iscrivendosi allo pseudo-pacchetto www.debian.org in tracker.debian.org e attivare la parola chiave vcs. Questi sono i passaggi (da seguire solo una volta):

  1. Aprire con un browser web https://tracker.debian.org/pkg/www.debian.org.
  2. Iscriversi allo pseudo-pacchetto www.debian.org (ci si può autenticare con SSO oppure, se non si usa già tracker.debian.org per altri motivi, registrarsi con email e password).
  3. Andare su https://tracker.debian.org/accounts/subscriptions, poi su modify keywords, mettere la spunta su vcs (se non c'è già) e salvare.
  4. Da questo momento in poi verrà inviata una email ogni volta che qualcuno fa un commit nel repository di webwml.

Recezione di notifiche di Merge Request

Chi desidera ricevere delle notifiche via email quando sono inserite delle nuove merge request per il repository webwml su Salsa, può configurare le impostazioni di notifica tramite l'interfaccia web, seguendo questi passaggi:

  1. Accedere con il proprio utente Salsa e andare alla pagina principale del progetto.
  2. Fare clic sull'icona con la campanella nella parte alta della pagina principale del progetto.
  3. Scegliere il livello di notifiche preferito.