Jump to content

Sviluppo/gerrit/CaricamentoPatch

From The Document Foundation Wiki
This page is a translated version of the page Development/gerrit/SubmitPatch and the translation is 80% complete.

Inviare una patch per la revisione su gerrit

Caricare le patch per la revisione

Stephan Bergmann ha fatto una presentazione utile in FOSDEM 2021 chiamato The Perfect Gerrit Patch - un rapporto dei consumatori.

Importante: normalmente non c'è mai un motivo per abbandonare la patch. Si prega di leggere attentamente la sezione su invio di una nuova versione.

Create ed inviate le vostre modifiche su gerrit affinché vengano revisionate (la documentazione ufficiale di gerrit si trova qui):

git checkout -b <un_nome_a_vostra_scelta_per_la_branch_locale> origin/master
# Apportate le modifiche al codice ed assicuratevi che venga compilato
git add file1 [file2 ...] # tutti i file nuovi _e_ quelli modificati
git commit
./logerrit submit master

Nota: affinché il comando `logerrit` funzioni, assicuratevi di esservi iscritti a gerrit e predisposto tutte le impostazioni. Qui potete trovare le istruzioni per farlo.

Il primo comando crea un nuovo ramo e fa in modo che tenga traccia del ramo remoto origin/master. Ciò consente di seguire ./g pull -r per ribasare automaticamente il vostro ramo sull'ultimo master, che potrebbe essere una precondizione necessaria per l'invio, quando il vostro ramo diventa più vecchio di una settimana .

Se avete creato un ramo senza specificare un ramo remoto da tracciare, e ora ./g pull -r non ribasa automaticamente il ramo, potete anche usare il comando git branch -u origin /master su un ramo esistente per avviare il monitoraggio.

Nota: i passaggi git add + git commit possono essere eseguiti usando 'git gui', ricordatevi che la riga dell'oggetto del commit non dovrebbe essere più lunga di 72 caratteri e le righe del messaggio di commit, se presenti, non dovrebbero superare gli 80 caratteri.

Nota: per gli invii al ramo master, è utile che le modifiche si basino su di una versione recente del master, in modo che le compilazioni CI su jenkins possano trarre il maggior beneficio possibile dall'uso di ccache.

Nota: LibreOffice utilizza clang-format per controllare la conformità delle patch alle regole prestabilite. Viene usata una specifica versione di clang-format (per evitare delle discrepanze che sussistono tra le sue diverse versioni, anche tra rilasci minori). Se sul vostro sistema clang-format non è preinstallato, al momento dell'esecuzione di git commit, verrà generato un avvertimento riportante le istruzioni per installare gli eseguibili richiesti. Se avete già una versione preinstallata potreste non visualizzare alcun avvertimento (ma potreste ottenere risultati incongruenti nel caso in cui i bot di compilazione falliscano invitandovi a modificare la formattazione in modo diverso), oppure la versione preinstallata potrebbe non funzionare (ad es.: lamentandosi per le opzioni passate dalla riga di comando). Potete verificare la versione usata da LibreOffice su https://dev-www.libreoffice.org/bin/.

Solamente l'ultima riga è speciale ed effettuerà il push di tutte le patch presenti nella branch locale avente il nome indicato, inviandole alla coda di revisione della branch master (Se volete inviare una patch alla branch di un rilascio, o ad altre branch, modificate i comandi di conseguenza). In qualità di contributori occasionali la vostra patch dovrà indicare lo stesso indirizzo email del vostro account su gerrit altrimenti non vi sarà permesso di effettuare il push.

Se il push va a buon fine, git vi indicherà l'indirizzo dove si trova il vostro commit in attesa di revisione. L'url sarà simile a https://gerrit.libreoffice.org/#/c/229/.

È bene conservare la branch locale fino a quando la patch è in revisione, ciò vi consentirà di effettuare facilmente il push di una nuova versione della patch. Nel frattempo potete eseguire

git checkout master

per tornare alla branch master... e potete iniziare a lavorare ad un'altra patch usando nuovamente la procedura sopra descritta (creare una branch locale, scrivere il codice, effettuare il commit, fare il push su gerrit).

Aggiungetevi all'elenco dei contributori

Se è la prima volta che contribuite una patch al progetto LibreOffice, aggiungetevi all' elenco degli sviluppatori e contributori (seguite le istruzioni riportate in quella pagina) ed indicate la licenza per i vostri contributi.

Siete pregati di inviare la dichiarazione contestualmente al vostro primo caricamento di codice su gerrit (e non prima) ed assicuratevi di aver ottenuto dai vostri genitori il permesso per farlo!

Alternativa: uso di git review

In alternativa a quanto sopra, potete prendere in considerazione l'utilizzo di "git review", come spiegato nella pagina Development/GitReview.

Revisionare le patch

Il passaggio successivo dopo aver inviato una patch è quello di revisionarla collaborativamente su gerrit. Vedete Revisione delle patch per maggiori informazioni.

Spiegazione dettagliata di alcuni elementi relativi al caricamento delle patch

Caricare una nuova versione

Se durante la revisione di una vostra patch dovete caricarne una nuova versione, eseguite:

git checkout <branch_locale_associata_alla_vostra_patch>
<apportate le vostre modifiche>
git add ...
git commit --amend  # Modifica l'ultimo commit della branch invece di crearne uno nuovo. Qui non va mai usata l'opzione -m!
./logerrit submit master

Notate che gerrit rileva che si tratta di una nuova versione di una modifica esistente (tramite la riga Change-Id inserita automaticamente nel messaggio di commit quando è stato inviato originariamente).

Suggerimento:
Se per sbaglio vi dimenticate di usare --amend e vi ritrovate con 2 commit, potete unirli con git rebase -i; per le istruzioni vedete Git per gli sviluppatori di LibreOffice.


Usare git review per rettificare delle modifiche e caricare nuove versioni della patch

Rettificare manualmente le modifiche nel modo sopra descritto può rapidamente generare confusione e tenere traccia della branch_locale_associata_alla_vostra_patch può indurre in errore (in ogni caso, associata come?). Se avete caricato su gerrit molte modifiche, tenerle tutte nella branch master e rettificarle indipendentemente una dall'altra è impossibile. Dovrete reimpostare HEAD^ dopo ogni caricamento e scaricare/modificare/correggere/caricare/reimpostare per ogni nuovo insieme di patch, oppure farlo in branch separate, in questo può tornare utile git review.

Per sapere come fare, leggete Development/GitReview#Amending_a_gerrit_change.

Caricare delle patch come private o in lavorazione

Se usate il comando ./logerrit submit master%private al posto di ./logerrit submit master, creerete una modifica privata.

Questa modifica sarà visibile solamente a voi ed ai revisori che aggiungerete usando il pulsante 'add reviewer' presente in gerrit.

Se non avete la necessità di nascondere le vostre modifiche al pubblico, potete usare il comando ./logerrit submit master%wip per creare una modifica in lavorazione.

Se non usare logerrit, effettuate il push su riferimento/alla/branch%private o riferimento/alla/branch%wip.

Potete anche attivare lo stato "private" e "WIP" dall'interfaccia utente di gerrit.

Caricare patch da revisionare relative ai moduli dictionaries, helpcontent2, translations

Vedete la pagina dedicata ai Submodule.

Cherry picking yourself out of trouble

Ignoring the advice about submitting new versions of patches is common. This might lead to deleting a local branch or submitting a new patch depending on an older patch. In order to work on your original patch locally again, do the following:

  1. In a terminal, check out a new branch from master
  2. Click the kebab menu in the top right corner of the Gerrit patch view
  3. Select Download patch
  4. Click the copy button next to Cherry Pick
  5. Paste the copied command into your terminal
  6. Follow the modifying and amending advice from the section about submitting a new version

If the Jenkins CI build fails, but not due to your patch

If the patch-triggered CI build fails and you are certain it is unrelated to your patch, do not attempt to restart it by adding new changes (including rebasing against the master branch); instead, mention it in the #libreoffice-dev IRC:// IRC channel (or other equivalent channels), and one of the members with Jenkins access will re-run the failed builds using its resume function.

Some CI jobs (e.g., the ones that do the macOS builds) are configured to be re-run automatically when they fail. They can be identified via the "Refresh" icon in the R column of the job table.