TDF LibreOffice Document Liberation Project Community Blogs Weblate Nextcloud Redmine Ask LibreOffice Donate
This tutorial will show you how to find the code change that caused a regression bug. It is a good idea to go through a known clear investigation as your first learning step, because sometimes bibisecting and its results can be messy.
We will be investigating a bug that prevents us from opening a certain document. Testing a bug does not get any simpler: the only required action is trying to open the document.
Unfortunately, due to backwards compatibility issues at the operating system level, the specific bibisect repository used in the tutorial does not work with recent Linux and macOS versions. Linux and macOS testers can instead do the following and adapt the steps in the tutorial to match the ones in the chosen bug:
- go the advanced search in Bugzilla
- in the Summary field, input: fileopen crash
- pick --- and FIXED for the resolution
- add keywords bisected, regression
- in Custom Search select Version - matches regular expression and input a "starts with" pattern that matches a more recent version, for example ^7 to include all versions starting with 7 or ^7\.6 to limit to a specific major version
To get an idea of which version range the bug appeared in, you would normally need to test with multiple bibisect repositories or alternatively multiple parallel-installed release versions. To make things simpler for the tutorial, we start with the knowledge that the bug appeared in the 6.1 version range (6.0 branch point to 6.1 branch point and then 6.1.x minor releases).
To set up the bibisecting environment on Windows, Linux or macOS, install git. When installing Git for Windows, it is a good idea to select the option ”Checkout as-is, commit Unix-style line endings” because this is required, if you ever get into LibreOffice development.
Next, from a command line shell, download the 6.1 repository.
Windows (note: read all of the instructions behind the link - only step 1 is done differently with PowerShell).
Download command to use with PowerShell on Windows (do not use PowerShell 5, but the latest one):
Invoke-WebRequest -Uri https://bibisect.libreoffice.org/win32-6.1.git-bundle -OutFile win32-6.1.git-bundle -Resume
The downloading and processing of the repository will take a relatively long time (perhaps an hour, depends on your system).
When you do the steps for downloading and cloning, make sure you keep working in the correct directory. So if you take a break in between and turn off your computer, you must remember to change to the right directory next time.
Note that on macOS, you might have to right click and select open in Finder to verify the app the first time you use a new bibisect repository.
- Download attachment 157140 from tdf#130093. The rest of the steps will assume the document is in your typical Downloads directory.
- In your command line shell, enter the bibisect repository directory with the cd command.
- Give chained commands to checkout the oldest code commit in the repository and try to open the problematic document.
git checkout oldest && instdir\program\soffice 'C:\users\username\downloads\Lotus testfile.lwp'
git checkout oldest && instdir/program/soffice ~/Downloads/Lotus\ testfile.lwp
git checkout oldest && LibreOffice.app/Contents/MacOS/soffice ~/Downloads/Lotus\ testfile.lwp
- Observe, how the document opens just fine.
- Give the same chained commands as previously, but replace oldest with master. You can reach the previous command in the shell by using your up arrow keys. Move with your left/right arrow keys and Home/End keys and modify the command.
- Observe how you get a General input/output error for the document in the newest commit of the repository.
- If during this process you get an error saying your local changes to some Python files would be overwritten by checkout, use this command to throw away the changes:
git checkout .
- Again, bring up the chained commands, but replace the first one entirely with
git bisect start master oldest
- Bring up a previous chained command and if the document opened fine, replace the first command with
If you saw the error or a crash upon opening, replace the first command with
git bisect good
git bisect bad
- Continue this dance of goodness and badness until you see a block of text like this:
a8220993df5ae8b0e673e536c0d9dd7b458e55db is the first bad commit commit a8220993df5ae8b0e673e536c0d9dd7b458e55db Author: Norbert Thiebaud <nthiebaudgmail.com> Date: Mon Feb 12 13:20:52 2018 -0800
The above bad commit result is taken from the Windows 6.1 repository. The bad commit refers to the binary build in the repository itself. The actual source commit is the hash string after "source sha:". The person next to "Author:" is the one who created the bibisect repository and has nothing to do with the regression bug.
If you want to verify that the result is correct, you can do a checkout for the binary commit (the exact hash depends on the repository you use)
git checkout a8220993df5ae8b0e673e536c0d9dd7b458e55db
and try to open the document (you should see the read error). Then checkout the previous commit with
git checkout HEAD^
Now you should be able to open the document.
You can view the details of the code change by taking the "source sha" string and putting it in a URL that you can then visit: https://git.libreoffice.org/core/commit/22fc8c634c5f9b09d45aff0403503f4d8226328d
In the code changes we can see that it is dealing with the lotuswordpro module, which is in line with the topic.
Making the results public
Sometimes a regression has already been reported and analysed. This means we should always do a search in Bugzilla before declaring our results.
- Go to the advanced search in Bugzilla.
- Hold down Ctrl key and left-click the --- below "Resolution:". This will allow you to search both open and closed reports.
- Expand the Detailed Bug Information section.
- Paste the "source sha" string into the Comment field.
- In the Keywords field, type regression and click the Search button.
In the case that no reports are found, do these steps in the report that requested bibisecting:
- Remove the keyword 'bibisectRequest' from Keywords field and add the keyword 'bibisected'.
- If the commit causing the regression has been identified (as in this tutorial), also add the keyword 'bisected'.
- Add the blamed developer to CC (note: this is not the author of the commits of the bibisect repo - you have to view the details of the code change as described in the Analysis section).
- In your comment, mention which bibisect repository you used, show the blamed commit and include the text 'Adding Cc: to <developer's name>'
Below is a video representation of the tutorial done under Windows 10 and using PowerShell 7.