JM/Bibisect
TDF LibreOffice Document Liberation Project Blog Komunitas Penerjemah Weblate Nextcloud Redmine Tanya LibreOffice Donasi
Pengantar
Bibisect merupakan singkatan dari "binary bisect", yaitu prosedur yang membantu mengidentifikasi commit yang menyebabkan regresi. Regresi adalah artefak yang paling menjengkelkan yang sayangnya muncul serta bersamaan dengan pengembangan perangkat lunak dan PK. Kita ingin menangani regresi secepat mungkin karena seiring waktu berlalu, semakin sulit untuk melakukan triase dan perbaikan.
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.
Bagaimana Bibisecting Bekerja?
Setiap paket bibisect adalah repositori git yang diisi dengan ratusan atau ribuan build LibreOffice. Ditambahkan ke repositori dalam urutan kronologis, build ini menyediakan cara cepat dan sederhana bagi kita untuk menguji kutu pada banyak versi berbeda tanpa harus mengkompilasi LibreOffice setiap kali kita beralih ke versi yang berbeda.
Kita dapat memanfaatkan alat-alat yang dibangun di dalam git untuk pencarian biner melalui commit (misalnya git bisect) serta mendapatkan manfaat dari fungsi kompresi dan de-duplikasi yang termasuk dalam git. Misalnya, dalam serangkaian build yang masing-masing mungkin membutuhkan ruang disk 500MB, melalui de-duplikasi kita berpotensi hanya menggunakan 25MB per build tambahan.
Rincian
Bibisect yang berhasil akan membantu pengembang hanya memiliki sedikit commit untuk dicari untuk menemukan commit 'pelaku' yang kita yakini memperkenalkan regresi. PK dapat melakukan langkah tambahan membagi dua sepenuhnya (menentukan commit yang tepat) atau dapat menyerahkan ini kepada pengembang. Seringkali mudah untuk menemukan commit yang menyebabkan masalah setelah melakukan bibisect kutu.
Dengan sekitar 10 giga, Anda akan memiliki ratusan build untuk dikerjakan. Bibisect dapat memakan waktu hanya 15 menit.
Seperti yang dapat dilihat dari Commit dalam kisaran dan Jumlah build, tergantung pada repositori bibisect tertentu, kisaran ini mungkin rata-rata 80 commit untuk repositori "43max" lama (mencapai ratusan dari commit sumber dalam beberapa build) menjadi hanya 1 atau 2 commit untuk repositori yang lebih baru. (Kami juga memiliki beberapa repositori bibisect yang sangat 'kasar' yang menggunakan versi yang dirilis + beta + RC builds, dan ini mungkin memiliki rentang yang mencakup ratusan commit).
Petunjuk Umum
Bisa jadi ide yang baik bagi pemula untuk memulai dengan menelusuri langkah-langkah bibisect yang sudah selesai dengan sukses. Untuk tujuan ini kami memiliki tutorial bibisecting.
Bibisecting bergantung pada 6 langkah:
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):
- 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.
- Update the Version field, if needed (see also #Finding the earliest version affected
- 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)
- Add the name of the commit author to the Regression By field (for this you need contributor rights in Bugzilla)
- Add the commit author to the CC List of the report
Note that you should only add the original author to the CC ("author" on git.libreoffice.org, or "owner" on gerrit), not any reviewers. If a developer has retired from the project (check the date of their last commits), there is no point in adding anyone to the CC.
Commit ranges
Some bibisect repositories have ranges of source commits folded into a single chunk. If after completing a bibisect you are presented with only a single one of these chunk commits, you can get the range by first copying the hash (note: not the source hash) and using it in a git log command like so:
git log -2 c3f9dc54188b316a61dd871b63734d49b05f5d7f
Now you can copy the source hashes of the first and previous displayed commits and separate them with ..
to construct a range query like so:
https://git.libreoffice.org/core/log/7c4d3ea6ba4d42b4dda5148a00c8c411b5d7703d..5b195fbcf7a441aeb193f6abd08b877e580938e0
This will allow you to skim commit messages looking for related subjects. For deeper scrutiny, see the section on detective work.
Finding the earliest version affected
If you have a local copy of the core repository, you can update the Version field in the bug report thanks to some git commands:
1. First, make sure you have all the tags:
git fetch --tag
2. Then, use `name-rev` to find the context (more precisely, by how many revisions it preceded the earliest tag that contains the commit):
git name-rev <commit>
3. If that didn't give a useful tag that matches a LibreOffice version, you can list all tags that contain the commit and have "libreoffice" in the name with:
git tag --contains <commit> | grep libreoffice
Limitations
Performing a bibisect is only possible if we have a repository available for the correct OS, covering the correct range of LibreOffice commits.
Some regressions are difficult to reproduce, and may require multiple test runs for a bug to appear. As you may imagine, trying to bibisect such regressions is very difficult, and requires one to perform many test runs after each checkout of a new version of LibreOffice to give some security / statistics that the bug is indeed present or not present with the given version.
We do not currently have bibisect support for
- LibreOffice for Android
- BSDs (although the GNU/Linux bibisect packages may run, with minor tweaks)
- LibreOffice Online
- LibreOffice Vanilla for Mac (in the Mac App Store)
Not Bibisectable
Some bugs are not bibisectable. These include
- 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
If a bug with bibisectRequest Keyword is found to be not bibisectable, leave a comment on the bug explaining why we're not able to use bibisect to track down the introduction of this problem, and replace Keyword bibisectRequest with notBibisectable. If a bug predates bibisect builds, replace Keyword bibisectRequest with preBibisect.
Finding bugs
Menemukan kutu yang membutuhkan 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.
The following bugs with keyword bibisectRequest are waiting for a bibisect:
In addition all unresolved regressions in LibreOffice might benefit from bibisecting.
Special situations
Bibisecting language-specific bugs
The TDF bibisect repositories provided do not include any lang-packs.
To bibisect bugs which work good with english UI, but bad with non-english UI (like CJKs): one should copy-paste the following files, from a release build which has your language, to the same location of the bibisect repo:
- program/resource/<your_lang_tag>
- share/registry/Langpack-<your_lang_tag>.xcd
- share/registry/res/fcfg_langpack_<your_lang_tag>.xcd
- share/registry/res/registry_<your_lang_tag>.xcd
The suggested language resources you should copy is the one for the same major branch. For example, for the bibisect-linux-64-6.0 repo, you can copy from 6.0.1.1 release.
Running with a separate user profile
To create separate profile directory in /tmp/ (which will be automatically removed during the next machine boot):
./opt/program/soffice -env:UserInstallation=file:///tmp/soffice-bisect
If you want to start fresh for each bisect iteration, you can add git commit hash to directory name. For example:
./opt/program/soffice \
-env:UserInstallation=file:///tmp/soffice-bisect-$(git rev-parse HEAD)
Finding a fix
Sometimes a bug is a collateral damage of another (possibly minor) bug, in a non obvious way. In such cases that other bug might be fixed on master, but was not backported to the release branch. To identify a problem-fixing commit you can use:
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
As you test, say
git bisect fixed
or git bisect unfixed
as appropriate.
If the fix is small and important enough, it likely can be easily backported to the release branch.
Checking out a specific commit based on source hash
Sometimes you already know a specific source commit has/does not have the bug you are hunting.
Copy the source hash from the LibreOffice git history and use it to grep in the bibisect repo log like so:
git log --all --grep='29a9f433c268414747d8ec7343fc2b5987971738'
Copy the commit hash of the bibisect repo and do a checkout for it to verify your assumption:
git checkout 38758b70f5278d4d8292a2e857e80a9a1130f38e
You can use the repo commit hash when determining the bad-good range to bisect:
git bisect start 38758b70f5278d4d8292a2e857e80a9a1130f38e oldest
Doing detective work inside a commit range
In case your bibisect result is a range of commits and you have trouble locating the offending commit, you might make your life easier by searching with a keyword.
An example for a case, where we know the problem is in Calc's Navigator view:
git log --stat --pretty=short --graph 169bd7718264b0e312052757f9bbd2321e1399c2...ff8b873936aa72b17309da4bfc2775573a5b1f55 | grep -B 10 -A 10 --color=always "sc/source/ui/navipi" | less -R
Adjust the -B and -A grep parameters to control how many lines before and after the hit you want to display. When piping to less, -R preserves the colouring of search results.
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.
If soffice
is failing with a non-zero exit code - this probably means a crash - a solution under QA/Bibisect/Automation#Tidbits for efficiency offers a script to ease the pain of repeatedly skipping failed probes.
Especially in the older repositories, sometimes you can end up with a list of dozens of potential bad commits. The commits might not be in order, so it is not easy to construct a range query. You can save the list of commits to a text file and run git show
for all of them, directing the output to a file:
while IFS="" read -r p || [ -n "$p" ]
do
git show --no-patch "$p" >> /path/to/bisectlog.txt
done < /path/to/bisect_range.txt
The older repositories include the original commit message, so this resulting log file will be immediately useful. If the binary repository doesn't include the original messages, you have to first do a pass with git show --oneline --no-patch
, tidy up the list of source hashes and then do the final looping against LibreOffice core repository.
Finding source commits from bibisect
If bibisect was done, but not likely to be correct or in a repository known to have large range of source commits, we can check the range by finding a previous build commit from the found one and then find the source range.
$ git log -1 1f14665c5624bc7a502738aa8f4f2bd70a211e72^
$ git log --oneline b6c016da23d309b4ac7d154bc33a22397974ed73..d85fd8a85501547d5bb87822d2589a07aed7f2d6
Troubleshooting
This section covers issues that affect more than one OS. For OS-specific issues, please see the individual OS wiki pages.
Unable to extract files
If you can't extract files (you should get an error message), try to rename the file from *.tar.lzma to *.tar.xz.
Installed LibreOffice became modified unexpectedly
Problem / Messages:
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
Solutions:
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;
The above command will repair the problem. Afterwards you can start the next test run as usual with
git bisect good # or git bisect bad
If that does not solve the problem, you can try the following commands:
git clean -fd
git reset --hard
The ultimate repair is to delete everything except one hidden .git/ folder, and do
git checkout oldest
Unable to start soffice
Upon trying to run soffice
within bibisect you receive the error "unexpected operator terminate called after throwing an instance of 'com::sun::star::uno::DeploymentException'
Solution: Reset your Libreoffice profile. Make sure to backup the folder, if you have any settings you'd like to preserve for use with your stable LibreOffice release. After you're done with the bibisect you can try to return your backed up profile to its original location (ie. delete the profile folder and replace it with the backed up one)
How to bisect RTL bugs
In case you need to bisect a RTL ( Right-To-Left ) bug, run LibreOffice with this environment variable (see the link to learn how to use environment variables on different platforms):
SAL_RTL_ENABLED=1
How to bisect File Recovery bugs
In case you need to bisect File Recovery bugs ( e.g. tdf#129210 ), comment out line OOO_DISABLE_RECOVERY=1 in file instdir/program/ooenv
You may also use user control:
soffice --norestore file-that-recovers.ext
How to bisect file hanging / CPU or memory exhaustion bugs
In case you need to bisect file hanging/memory exhaustion bugs, you may limit memory or CPU or time execution.
In Linux, timeout utility can be used. To avoid confusion with built-in "timeout" command, here it's renamed to "tmt".
For example, if LibreOffice 'good' commit opens a file with 1 GB of memory, you may set soffice memory limit to 1.500.000 kilobytes to avoid 'bad' commit hanging your computer.
tmt -m 1500000 instdir/program/soffice
Or, to limit CPU+SYS time (where normal time is seen with successful run):
tmt -t 20 instdir/program/soffice
More advanced option is to use benchexec utility. User needs to be added to the appropriate group (benchexec). Runexec can be used to execute a single command while measuring its resource consumption, similarly to the tool "time" but with more reliable time measurements and with measurement of memory usage.
In Windows, process-governor utility can be used.
Further information
Automation
See the separate article on automating bisecting.
notes
For details on how the bibisect archives are generated: