Fuchsia

Bisect product bundles

The ffx product-bundle bisect command helps identify regressions in product bundles by bisecting over assembly artifacts.

Concepts

When a bug or behavior change occurs between two versions of a product bundle, ffx product-bundle bisect can help pinpoint which specific artifact (platform, board, or product) introduced the change. It does this by:

  1. Generating a list of released versions between a known-good version (--from-success) and a known-bad version (--to-failure).
  2. Assembling intermediate product bundles using combinations of artifacts from different versions.
  3. Facilitating tests on these intermediate bundles to determine if they pass or fail.

By using a binary search (or median cut) approach over the artifacts, the tool quickly narrows down the source of the regression.

Usage

You can run the bisection manually by following the prompts from the tool.

Manual Bisection

To start a bisection between two known versions of a product bundle, run:

ffx product-bundle bisect <name> --from-success <version> --to-failure <version>

Replace <name> with the name of the product bundle (e.g., core.vim3) and <version> with the product bundle version numbers.

The tool will assemble intermediate bundles and prompt you to test them. After testing, you inform the tool whether the step passed or failed, and it calculates the next step.

Pausing and Resuming

You can pause the bisection process at any time by pressing CTRL+C. The tool saves its state. The next time you run the exact same ffx product-bundle bisect command, it will ask if you want to continue the previous run or start over.

Options

Detailed options for ffx product-bundle bisect:

  • --from-success: Known-good version of the product bundle.
  • --to-failure: Known-bad version of the product bundle.
  • --slot: Slot to bisect over (a or r). Defaults to slot a.
  • --out-dir: Directory to write assembled images and other artifacts. Defaults to ~/plan_directory/out.
  • --gen-dir: Directory to write intermediate files. Defaults to ~/plan_directory/gen.
  • --auth: Authentication method to use for fetching artifacts.

Examples

Bisecting a product bundle manually:

Note: core.vim3 is used as an example, but may have limited support depending on your environment.

ffx product-bundle bisect core.vim3 \
    --from-success 29.20250826.6.1 \
    --to-failure 29.20250905.6.1