Using git to manipulate website source code

Introduzione

Git è un sistema per il controllo delle versioni che aiuta nella gestione di più persone che lavorano simultaneamente sullo stesso materiale. Ogni utente detiene una copia locale di un repository principale. Le copie locali possono essere sulla stessa macchina oppure sparse su tutto il pianeta. Gli utenti possono modificare la copia locale a proprio piacimento e quando hanno completato la loro attività, salvano (commit) e inviano (push) le modifiche al repository principale.

Git non permette di inviare un commit al repository remoto se quest'ultimo ha altre modifiche più recenti rispetto alla propria copia locale sullo stesso branch. Nel caso in cui si verifichino dei conflitti, recuperare e aggiornare la propria copia locale e eseguire rebase delle proprie modifiche con l'ultima versione del repository.

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 debian-www@lists.debian.org 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 (consultare Project forking workflow e When you work in a fork per i dettagli).

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.

Operazioni con il repository

Recuperare una copia locale del repository

Come prima cosa per poter lavorare con il repository occorre installare git. Poi impostare il proprio utente e indirizzo email sul computer (far riferimento alla documentazione di git su come fare queste configurazioni). Infine è possibile clonare il repository (cioè creare la copia locale) in uno dei seguenti modi.

Per lavorare su webwml si raccomanda come prima cosa di registrarsi su salsa.debian.org e attivare l'accesso a git tramite SSH abbinando una chiave pubblica SSH al proprio utente salsa. Consultare le pagine di aiuto di salsa per ulteriori informazioni su come farlo. Poi sarà possibile clonare il repository webwml utilizzando il comando seguente:

   git clone git@salsa.debian.org:webmaster-team/webwml.git

Coloro che non hanno un account salsa possono, in alternativa, clonare il repository usando il protocollo HTTPS:

  git clone https://salsa.debian.org/webmaster-team/webwml.git

In questo modo si ottiene comunque una copia locale del repository ma non è possibile inviare (push) direttamente le modifiche.

La clonazione dell'intero repository webwml richiede di scaricare circa 500MB 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 git@salsa.debian.org: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

Checkout parziale del contenuto

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

   $ git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
   $ cd webwml
   $ git config core.sparseCheckout true
   In webwml: Creare il file .git/info/sparse-checkout con contenuto simile
   a questo (per i soli file di base, le pagine in inglese e le traduzioni in
   spagnolo e catalano):
      /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
   Infine:
   $ 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:

   $ git pull

Adesso modificare i file e, una volta completato, eseguire il commit delle modifiche sul proprio repository locale con:

   $ git add percorso/al/file
   $ git commit -m "Messaggio di commit"

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

Se non si dispone dell'accesso in scrittura al repository webwml, si possono inviare le proprie modifiche tramite la funzionalità di Merge Request messa a disposizione dalla piattaforma Salsa GitLab oppure chiedere aiuto agli altri sviluppatori.

Questo è un semplice riepilogo di come usare git per manipolare il codice sorgente del sito web Debian. Per ulteriori informazioni su gir, consultare la documentazione di git.

Chiudere bug Debian con commit

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 HTTPS verso questi siti.

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 - prende le modifiche e aggiorna 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.

Recezione di notifiche

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):

Recezione di notifiche di Merge Request

Chi desidera ricevere delle notifiche via email quando sono inserite delle nuove Merge Request per il repository webwml sulla piattaforma Salsa GitLab, può configurare le impostazioni di notifica relative al repository webwml tramite l'interfaccia web, seguendo questi passaggi: