Skip to content

docs: document partial-failures.json for multi-version bootstrap #1321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
LalatenduMohanty merged 1 commit into from
Sep 8, 2026
Merged

docs: document partial-failures.json for multi-version bootstrap #1321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 30 additions & 1 deletion docs/how-tos/multiple-version-bootstrap.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,18 +80,47 @@ Output Files

When ``--multiple-versions`` is active:

.. versionchanged:: 0.95.0
Failed versions are recorded in ``partial-failures.json``. The file is
removed when a subsequent run has no reportable failures.

- ``build-order.json`` --- created normally, listing every version built
- ``graph.json`` --- created normally, containing all versions in the
dependency graph
- ``partial-failures.json`` --- created when one or more versions fail. Each
failure includes the package name, version, phase, exception type, and
message.
- ``constraints.txt`` --- **not generated**

The report contains a top-level ``failures`` list. For a resolved version,
``name`` includes the package version (for example, ``requests==2.28.0``),
and ``version`` contains the version separately. For an unresolved
requirement, ``version`` is ``null`` and ``name`` contains only the package
name.

.. code-block:: json

{
"failures": [
{
"name": "requests==2.28.0",
"version": "2.28.0",
"phase": "failed during build phase",
"error_type": "CalledProcessError",
"message": "build command failed"
}
]
}

Combining with Other Flags
--------------------------

``--test-mode``
Supported with serial ``bootstrap`` only. Failures are collected and
reported at the end rather than aborting early (same behavior as without
``--multiple-versions``).
``--multiple-versions``). When combined with ``--multiple-versions``,
failed versions are also included in ``partial-failures.json`` and test
mode retains its non-zero exit code for recorded failures.

``--skip-constraints``
Redundant when ``--multiple-versions`` is set. Fromager automatically
Expand Down
6 changes: 4 additions & 2 deletions docs/proposals/test-mode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,15 +89,17 @@ graph node `pre_built` reflects settings only (not updated after fallback).
| -- | -- | -- |
| Purpose | Source-build gap analysis | All matching versions |
| On build failure | Pre-built fallback, keep traversing | Remove version from graph |
| Output | `test-mode-failures-*.json` | Logs only |
| Output | `test-mode-failures-*.json` | `partial-failures.json` |

## Usage

```bash
fromager bootstrap --test-mode -r requirements.txt
```

Review `test-mode-failures-*.json`, `build-order.json` (`source_url_type: "prebuilt"`), and `graph.json`. Tests: `tests/test_bootstrap_test_mode.py`,
Review `test-mode-failures-*.json`, `partial-failures.json` for failed
multi-version builds, `build-order.json` (`source_url_type: "prebuilt"`), and
`graph.json`. Tests: `tests/test_bootstrap_test_mode.py`,
`e2e/test_mode_*.sh`.

## Limitations
Expand Down