Introduction

Bibisect stands for "binary bisect". It's a procedure that helps identify commits that have caused regressions. Regressions are a most annoying artifact that unfortunately come with software development and QA. We want to deal with regressions quickly before time passes and they get harder and harder to triage and fix.

How does Bibisecting Work?

Each bibisect package is a git repository populated with hundreds or thousands of builds of LibreOffice. Added to the repository in chronological order, the builds provide a fast and simple way for us to test a bug against many different versions without having to compile LibreOffice each time we switch to a different version.

We can leverage the tools built into git for binary search through commits (e.g. git bisect) as well as benefit from the compression and de-duplication functions included in git. For example, in a series of builds that each might take up 500MB of disk space, through de-duplication we can potentially use only 25MB per additional build.

Details

A successful bibisect will leave developers with only a few commits to search through to find the 'culprit' commit that we believe introduced a regression. Depending upon the particular bibisect repository, this range might be 60, 100, or even 2 commits. (We also have some very 'coarse' bibisect repositories that use released versions + beta + RC builds, and these may have ranges spanning multiple hundreds of commits)

QA can go the additional step of fully bisecting (determining the exact commit) or can leave this to the developers. It's often easy to find the commit that caused the issue after bibisecting the bug.

With approximately 10 gigs, you'll have hundreds of builds to work with. A bibisect can take as little as 15 minutes.

General Instructions

It might be a good idea for beginners to start by tracing the steps of a bibisect that was already completed successfully. For this purpose we have a bibisecting tutorial.

Note: Each operating system is different, please read the full instructions that correspond to your specific operating system (GNU/Linux, macOS, or Windows) for more complete instructions, instructional videos, and other related information.

Bibisecting relies on 6 steps:

Setting up your environment, including installing any extra software

Downloading the bibisect package

Bibisecting the bug

Getting a bibisect log

Attaching the bibisect log to the bug report

Remove keyword 'bibisectRequest' from Keywords field and add the keyword 'bibisected'

If the commit causing the regression has been identified, also add the keyword 'bisected', add the developer as CC and add the comment 'Adding Cc: to <developer's name>'

Note that you should only add the original committer to the CC, 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. Rather in this case, you should bump the priority of the bug report.

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:

Limitations

Performing a bibisect is only possible if we have a repository available for the correct OS, covering the correct range of LibreOffice commits. We have very good coverage on GNU/Linux, and are improving our coverage on Windows and macOS.

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.

Versions

Not Bibisectable

Bugs that predate our bibisect builds (We're working on extending the range covered)

Bugs that depend upon build options not enabled in the TDF builds (e.g. -kde)

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.

Finding bugs already bibisected

With the above info added to the bug a developer knows that the regression was introduced between the commits fb754a0df859e30255c25af8fa19bfaa75f257e7 (good) and 2d19e9bb07ccff3134f855812dddfda5c07b1fe4 (bad) on master. A:

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

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:

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.

Troubleshooting

Please add your problems and how you solved them. 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 .

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

git clean -fd
git reset --hard

The ultimate repair is to delete everything except one

.git/

hidden folder, and do

git checkout oldest

Unable to start soffice

Problem: 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 located in ~/.config/libreoffice. 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 bibisect you can try to return your backed up profile to it's original location (ie. delete the new 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, please import this variable before calling LibreOffice:

SAL_RTL_ENABLED=1

Tidbits for efficiency

The repetitive nature of bibisecting gets tedious fast, so every trick you can use to make the process quicker is valuable. A typical way is to define aliases for complex commands in your .bashrc file.

The .bashrc of an active bibisecter might include a block such as this:

We have commands for jumping to the next or previous commit, "pycache" for dealing with a Windows-specific annoyance and finally "source" for quickly displaying source commit information. The command named "source" assumes you are in a bibisect repository, grabs the source hash of the currently checked out commit and feeds it to a git command targeting a full clone of the LibreOffice source code. To get a breakdown of the command, see the Bash Reference Manual.

The above examples are not exclusive to *nix systems, but work fine in a cygwin environment on Windows. If you want to open documents from the cygwin command line, enclose the ordinary Windows path in single quotes like so:

Please note that all contributions to The Document Foundation Wiki are considered to be released under the Creative Commons Attribution-ShareAlike 3.0 Unported License, unless otherwise specified. This does not include the source code of LibreOffice, which is licensed under the GNU Lesser General Public License (LGPLv3). "LibreOffice" and "The Document Foundation" are registered trademarks of their corresponding registered owners or are in actual use as trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy (see Project:Copyrights for details). LibreOffice was based on OpenOffice.org.If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it here.