Controllo di qualità - Bibisect

    From The Document Foundation Wiki
    < QA
    This page is a translated version of the page QA/Bibisect and the translation is 65% complete.
    Outdated translations are marked like this.

    Introduzione

    Bibisect significa "binary bisect". È una procedura che facilita l'identificazione dei commit che hanno causato una regressione. Le regressioni sono gli artefatti più fastidiosi che purtroppo fanno parte dello sviluppo e del controllo di qualità. Vogliamo gestire le regressioni rapidamente prima che il tempo passi e diventi sempre più difficile gestirne il triage e la risoluzione.

    If you are new to the topic of bisecting, it is recommended to first complete our tutorial and only then return to this article. Also, while you are free to study the topic independently, mentoring is available for all.

    Come funziona il Bibisect?

    Ogni pacchetto di bibisect consiste in un repository di git popolato con centinaia o migliaia di compilazioni di LibreOffice. Queste sono aggiunte al repository in ordine cronologico, le compilazioni forniscono un modo veloce e semplice per testare un bug su diverse versioni senza dover compilare ogni volta LibreOffice che si passa a una versione differente.

    È possibile fare uso degli strumenti incorporati in git per la ricerca dei binari nei commit (es. git bisect), così come beneficiare delle funzioni di compressione de-duplicazione incluse in git. Per esempio, in una serie di compilazioni, ciascuna delle quali può occupare anche 500MB di spazio su disco, attraverso la de-duplicazione si possono potenzialmente usare solo 25MB per compilazione aggiuntiva.

    Dettagli

    Un bibisect eseguito bene lascierà agli sviluppatori solo pochi commit tra i quali cercare il 'colpevole' che si suppone abbia introdotto una regressione. Il controllo di qualità può eseguire il passaggio aggiuntivo del bisect completo (determinando l'esatto commit) oppure lasciarlo agli sviluppatori. Dopo il bibisect del bug, spesso è facile trovare il commit che ha causato il problema.

    Con approssimativamente 10 giga, avrete centinaia di compilazioni sulle quali lavorare. Un bibisect può richiedere meno di 15.

    Attualmente, il bibisect è possibile su:

    Come potete vedere dai Commits in range e dal Number of builds nella tabella, a seconda di un determinato repository di bibisect, l'intervallo può essere in media di 80 commit per il vecchio repository "43max" (raggiungendo centinaia di commit dei sorgenti per alcune compilazioni) fino a 1 o 2 commit per i repository più recenti. (Ci sono anche dei repository di bibisect molto 'grezzi' che utilizzano le versioni di rilascio + le beta + le compilazioni Release Canditate, questi possono avere intervalli che coprono diverse centinaia di commit).

    Istruzioni generali

    Per i principianti potrebbe essere una buona idea iniziare tracciando i passaggi di un bibisect che è già stato completato positivamente. Per questo scopo esiste un tutorial sul bibisect.

    Note pin.svg

    Nota:
    Each operating system is different, so please read the page that corresponds to your operating system (GNU/Linux, macOS or Windows) for more specific instructions, tips and troubleshooting.

    Prima di eseguire per la prima volta il Bibisect dovrete:

    The bibisecting articles for each operating system contain tables listing the available versions. In the "Download links" column of the table you will find links to pages explaining how to acquire the repositories. The repositories for old versions no longer receiving updates are offered as bundles. The repositories for still active versions can be periodically updated with the command git checkout master && git pull.

    If you are testing version 5.x or older, you have to read carefully the article for the operating system you are using and also check the comments column in the Version table. The older versions require various special considerations that this general article does not mention.

    Use the cd (change directory) command in your terminal to move between the different repositories. Jump to the oldest commit in a repository by saying git checkout oldest and to the newest by saying git checkout master. In some older repositories you have to use latest instead of master. Even if the bug report already points out the first version with the bug, always start by testing with both the oldest and the newest commits.

    The commands to launch LibreOffice from the bibisect repositories are as follows in the different operating systems:

    # Windows
    instdir\program\soffice
    </div>
    
    <div lang="en" dir="ltr" class="mw-content-ltr">
    # Linux
    instdir/program/soffice
    </div>
    
    <div lang="en" dir="ltr" class="mw-content-ltr">
    # macOS
    open LibreOffice.app/

    When you don't see the bug in oldest, but do see it in the newest commit, start bibisecting by saying git bisect start master oldest.

    After testing in LibreOffice and seeing the bug, say git bisect bad. If you don't see the bug, say git bisect good. If you were unable to test, say git bisect skip (note that there are various tips related to these scenarios in this and other articles).

    After the final step in the bibisecting process, you are presented with the first bad commit. Within the information given, you are interested in the source hash, which is a combination of letters and numbers. Now you can study the commit to see what it's about and who wrote it. If you have the LibreOffice source code on your computer, you can change to its directory and say git show 22fc8c634c5f9b09d45aff0403503f4d8226328d, the last part being the source hash. Otherwise you can examine the commit in a web browser by creating a URL like so: https://git.libreoffice.org/core/commit/22fc8c634c5f9b09d45aff0403503f4d8226328d

    Now update the bug report as follows (can be done in a single change):

    1. Write a comment mentioning the bibisect repository you used and the source hash (it will become a link in Bugzilla automatically). Any other useful information is welcome, of course.
    2. Update the Version field, if needed (see also #Finding the earliest version affected
    3. Replace the keyword bibisectRequest with bibisected and bisected (only include the last one, if you found the exact commit and not just a range of commits)
    4. Add the name of the commit author to the Regression By field (for this you need contributor rights in Bugzilla)
    5. Add the commit author to the CC List of the report

    Fate attenzione che dovreste aggiungere in CC solo l'autore del commit originale ("author" su git.libreoffice.org o "owner" su gerrit), non gli altri revisori. Se uno sviluppatore si è ritirato dal progetto (controllate la data del suo ultimo commit), non ha senso aggiungere qualcuno in CC. Piuttosto, in questo caso, dovreste innalzare la priorità della segnalazione di bug.

    Intervalli di Commit

    Alcuni repository di bibisect hanno intervalli di commit di sorgenti raggruppati in un singolo pezzo. Se dopo avere completato il bibisect vi si presenta uno solo di questi pezzi di commit, potete ottenere l'intervallo copiando prima l'hash (nota: non l'hash del sorgente) e usandolo all'interno di un log di git con un comando come:

    git log -2 c3f9dc54188b316a61dd871b63734d49b05f5d7f

    Ora potete copiare gli hash del sorgente del primo commit visualizzato e di quelli precedenti e separarli con .. per costruire una ricerca dell'intervallo in questo modo:

    https://git.libreoffice.org/core/log/7c4d3ea6ba4d42b4dda5148a00c8c411b5d7703d..5b195fbcf7a441aeb193f6abd08b877e580938e0
    

    Questo vi permetterà di scremare i messaggi di commit alla ricerca degli oggetti appropriati. Per un esame più approfondito, vedete la sezione sul lavoro di investigazione.

    Ricerca della prima versione interessata

    Se avete una copia locale del repository core, potete aggiornare il campo Versione nella segnalazione del bug grazie ad alcuni comandi di git:

    1. Per prima cosa, assicuratevi di avere tutti i tag:

    git fetch --tag

    2. Poi, usate `name-rev` per trovare il contesto (più precisamente, di quante revisioni precede il primissimo tag che contiene il commit):

    git name-rev <commit>

    3. Se questo non restituisce un tag utile a trovare una versione di LibreOffice, potete elencare tutti i tag che contengono il commit ed hanno "libreoffice" nel nome con:

    git tag --contains <commit> | grep libreoffice

    Limitazioni

    L'esecuzione di un bibisect è possibile solo se è disponibile un repository per il sistema operativo correntemente usato, che copra l'intervallo corretto di commit di LibreOffice. La copertura è molto buona in GNU/Linux e sta migliorando su Windows e macOS.

    Alcune regressioni sono difficili da riprodurre e possono richiedere più esecuzioni del test perché il bug si presenti. Come potete immaginare, provare a fare il bibisect di queste regressioni è molto difficile e richiede l'esecuzione ripetuta molte volte dei test dopo ogni uscita di una nuova versione di LibreOffice per fornire alcune certezze/statistiche che il bug è effettivamente presente o meno nella versione in esame.

    Attualmente non c'è supporto per il bibisect di

    Non adatti al Bibisect

    Per alcuni bug non è fattibile il bibisect. Questi comprendono:

    • Bug che non si presentano su di una piattaforma supportata (vedete #Limitazioni)
    • Bug precedono le compilazioni del bibisect (Si sta lavorando per estendere l'intervallo coperto)
    • Bug che dipendono da opzioni di compilazione non abilitate nelle compilazioni di TDF (es. -kde)
    • Bugs that don't show up on a supported platform (see #Limitations)
    • Bugs that predate our bibisect builds
    • Bugs that depend upon build options not enabled in the TDF builds

    Se un con la parola chiave bibisectRequest si rivela essere tra quelli su cui non è possibile eseguire il bibisect, lasciate un commento al bug spiegando perchè non siete stati in grado di usare il bibisect per rintracciare l'introduzione del problema e sostituire la parola chiave bibisectRequest con notBibisectable. Se un bug è precedente alle compilazione del bibisect, sostituite la parola chiave bibisectRequest con preBibisect.

    Trovare i bug

    Trovare i bug che richiedono il bibisect

    If you are new to bibisecting, click the Id column header until the list is sorted from highest Id to lowest. Compared to newer ones, when bibisecting older issues you will run into more surprises and greater complexity.

    I seguenti bug con la parola chiave bibisectRequest sono in attesa del bibisect:

    In aggiunta tutte le regressioni non risolte in LibreOffice potrebbero trarre beneficio dall'esecuzione di un bibisect.

    Situazioni particolari

    Bibisect di bug legati a una specifica lingua

    I repositori per il bibisect forniti da TDF non comprendono alcun pacchetto delle lingue.

    Per eseguire il bibisect di bug che funzionano correttamente con l'interfaccia utente in inglese, ma in modo errato con lingue differenti (come CJK): dovreste copiare e incollare i seguenti file, da una compilazione di rilascio che contiene la vostra lingua, nella stessa posizione dei repository del bibisect:

    1. program/resource/<identificatore_della_vostra_lingua>
    2. share/registry/Langpack-<identificatore_della_vostra_lingua>.xcd
    3. share/registry/res/fcfg_langpack_<identificatore_della_vostra_lingua>.xcd
    4. share/registry/res/registry_<identificatore_della_vostra_lingua>.xcd

    Le risorse suggerite per le lingue che dovreste copiare sono uniche per la stessa versione major. Ad esempio, per il repository bibisect-linux-64-6.0, potete copiarle dalla versione 6.0.1.1.

    Esecuzione con un profilo utente separato

    Per creare una cartella per il profilo separato in /tmp/ (che sarà automaticamente rimossa al successivo riavvio della macchina):

    ./opt/program/soffice -env:UserInstallation=file:///tmp/soffice-bisect

    Se volete iniziare in maniera pulita per ogni iterazione del bisect, potete aggiungere l'hash del commit di git al nome della cartella. Per esempio:

    ./opt/program/soffice \
    -env:UserInstallation=file:///tmp/soffice-bisect-$(git rev-parse HEAD)

    Trovare una soluzione

    Alle volte un bug è un danno collaterale di un altro bug (probabilmente minore), in modo non evidente. In questi casi l'altro bug dovrebbe essere risolto nel master, ma non ne è stato fatto il backport nella branch della versione. Per identificare il commit che risolve il problema potete usare:

    git bisect start --term-new=fixed --term-old=unfixed
    git bisect fixed master
    git bisect unfixed <some-old-sha> # you can use "git log --reverse" to detect the first revision in the bibisected package

    Mentre eseguite il test, dite

    git bisect fixed

    o

    git bisect unfixed

    a seconda del caso.

    Se la soluzione è piccola e abbastanza importante, è probabile che ne possa essere fatto il backport nella branch della versione.

    Verificate uno specifico commit in base all'hash del sorgente

    Alle volte sapete già che uno specifico commit di sorgente contiene o meno il bug al quale state dando la caccia.

    Copiate l'hash del sorgente dalla cronologia di git di LibreOffice e usatelo con grep nel log del repository di bibisect in questo modo:

    git log --all --grep='29a9f433c268414747d8ec7343fc2b5987971738'

    Copiate L'hash del commit del repository di bibisect ed eseguite un suo checkout per verificare la vostra supposizione:

    git checkout 38758b70f5278d4d8292a2e857e80a9a1130f38e

    Potete usare l'hash del commit del repository quanto determinate l'intervallo errati-buoni su cui eseguire il bisect:

    git bisect start 38758b70f5278d4d8292a2e857e80a9a1130f38e oldest

    Esecuzione dell'indagine all'interno di un intervallo di commit

    Nel caso in cui il risultato del bibisect sia un intervallo di commit ed abbiate problemi a localizzare il commit colpevole, potreste semplificavi la vita effettuando una ricerca con una parola chiave.

    L'esempio di un caso, nel quale si sa che il problema è nella visualizzazione del Navigatore in Calc:

    git log --stat --pretty=short --graph 169bd7718264b0e312052757f9bbd2321e1399c2...ff8b873936aa72b17309da4bfc2775573a5b1f55 | grep -B 10 -A 10 --color=always "sc/source/ui/navipi" | less -R

    Regolate i parametri -B e -A di grep per controllare quante linee prima e dopo quella trovata volete visualizzare. Quando invita a tramite la pipe, -R conserva la colorazione dei risultati della ricerca.

    This method can also be used as a shortcut in a situation, where you find yourself having to use git bisect skip over and over again due to some broken functionality.

    Se soffice fallisce restituendo un codice diverso da zero (questo probabilmente comporta un crash) una soluzione come in Curiosità per l'efficienza offre uno script per alleviare la frustrazione di ripetute prove saltate e fallite.

    Specialmente nei repository più vecchi, alle volte può capiare di ritrovarsi con un elenco di dozzine di potenziali commit errati. I commit potrebbero non essere in ordine, perciò non è semplice costruire un intervallo di ricerca. È possibile salvare l'elenco dei commit in un file di testo ed eseguire git show per ognuno di essi, indirizzando l'output ad un file:

    while IFS="" read -r p || [ -n "$p" ]
    do
      git show --no-patch "$p" >> /path/to/bisectlog.txt
    done < /path/to/bisect_range.txt

    Il vecchio repository comprende il messaggio originale di commit, perciò questo file di log risulterà immediatamente utile. Se il repository binario non comprende il messaggio originale, dovrete prima effettuare un passaggio con git show --oneline --no-patch, riordinare l'elenco delle hash dei sorgenti e poi effettuare un ultimo giro nel repository del core di LibreOffice.

    Trovare i commit sorgenti dal bibisect

    Se il bibisect è stato eseguito, ma non propriamente nel modo corretto o in un repository noto per avere un ampio intervallo di commit, potete controllare l'intervallo trovando il commit di una compilazione precedente a quella trovata e quindi trovare l'intervallo dei sorgenti.

    $ git log -1 1f14665c5624bc7a502738aa8f4f2bd70a211e72^
    $ git log --oneline b6c016da23d309b4ac7d154bc33a22397974ed73..d85fd8a85501547d5bb87822d2589a07aed7f2d6

    Risoluzione dei problemi

    Siete pregati di aggiungere i problemi che avete riscontrati e come li avete risolti. Questa sezione riguarda problemi che affliggono più di un sistema operativo. Per problemi specifici a un sistema operativo, vedete le singole pagine del wiki per ogni OS.

    Impossibilità di estrarre dei file

    Se non riuscite a estrarre dei file (dovreste ottenere un messaggio di errore). Provate a rinominare il file da *.tar.lzma a *.tar.xz.

    La versione installata di LibreOffice si modifica inaspettatamente

    Problema / Messaggi:

       error: Your local changes to the following files would be overwritten by checkout:
         opt/program/pythonloader.pyc
         opt/program/uno.pyc
         opt/program/unohelper.pyc
       Please, commit your changes or stash them before you can switch branches.
       Aborting
    

    Soluzioni:

    git checkout .
    
    # <span lang="en" dir="ltr" class="mw-content-ltr">Sometimes this more specific command is needed:</span>
    find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | xargs rm -rf;

    Il comando soprastante risolverà il problema. Dopodiché potrete iniziare l'esecuzione del prossimo test, come di consueto con

    git bisect good # or git bisect bad

    Se ciò non risolve il problema, potete provare i seguenti comandi:

    git clean -fd
    git reset --hard

    L'ultima soluzione è quella di cancellare tutto tranne la cartella nascosta .git/, ed eseguire

    git checkout oldest

    Impossibilità di avviare soffice

    Problema 1: Provando a eseguire soffice all'interno del bibisect ricevete il messaggio di errore "unexpected operator terminate called after throwing an instance of 'com::sun::star::uno::DeploymentException'"

    Soluzione: Reimpostate il profilo di LibreOffice che si trova in ~/.config/libreoffice. Assicuratevi di fare un backup della cartella se avete delle impostazioni che volete conservare per usarle con la vostra versione stabile di LibreOffice. Dopo aver terminato il bibisect potete provare a tornare al profilo salvato copiandolo nella posizione originaria (es. cancellate la cartella del nuovo profilo e sostituitela con quella del backup)

    Esecuzione del bisect di bug relativi a lingue RTL

    Nel caso dobbiate eseguire il bisect di un bug relativo a una lingua RTL (Right-To-Left - da destra verso sinistra), importate questa variabile prima di chiamare LibreOffice:

    SAL_RTL_ENABLED=1

    Esecuzione del bisect di bug relativi al Ripristino di File

    Nel caso dobbiate eseguire il bisect di bug relativi al Ripristino di File (es. tdf#129210), commentate la linea OOO_DISABLE_RECOVERY=1 nel file instdir/program/ooenv

    Potreste anche usare il parametro da linea di comando:

    soffice --norestore file-that-recovers.ext

    Esecuzione del bisect di file che si bloccano / bug che saturano la CPU o la memoria

    Nel caso dobbiate eseguire il bisect di bug che causano blocchi o esauriscono la memoria, potete limitare la memoria, l'uso della CPU o il tempo di esecuzione.

    In Linux, potete usare l'utilità timeout. Per evitare confusione con il comando incorporato "timeout", qui viene rinominato in "tmt".

    Per esempio, se il commit 'buono' di LibreOffice apre un file di 1 GB di memoria, potreste impostare il limite di memoria per soffice a 1.500.000 kilobyte in modo di evitare che un commit 'errato' causi il blocco del computer.

    tmt -m 1500000 instdir/program/soffice

    Oppure, per limitare il tempo di utilizzo di CPU+SYS (dove il tempo normale è rilevabile da un'esecuzione andata a buon fine):

    tmt -t 20 instdir/program/soffice

    Un'opzione più avanzata è quella di usare l'utilità benchexec. È necessario che l'utente sia aggiunto al gruppo appropriato (benchexec). Runexec può essere usato per eseguire un singolo comando misurando il suo consumo di risorse, in modo simile allo strumento "time" ma con misurazioni dei tempi più affidabili e con la rilevazione dell'uso della memoria.

    In Windows, potete usare l'utilità process-governor.

    Ulteriori informazioni

    Automazione

    Vedete l'articolo separato relativo all'automazione del bisecting.

    Note

    Per dettagli su come vengono generati gli archivi del bibisect: