docs: add architecture overview docs by LalatenduMohanty · Pull Request #1250 · python-wheel-build/fromager

LalatenduMohanty · 2026-07-11T03:02:20Z

Add architecture overview docs

Also add an AGENTS.md rule to keep the docs in sync when the architecture changes.

Closes: #1247

PR follows CONTRIBUTING.md guidelines

coderabbitai · 2026-07-11T03:02:50Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a73b5963-c093-4cfe-a7fd-5d8038323201

📥 Commits

Reviewing files that changed from the base of the PR and between 9766874 and ecdf478.

📒 Files selected for processing (7)

AGENTS.md
docs/concepts/architecture-overview.rst
docs/concepts/bootstrapper-architecture.rst
docs/concepts/hooks-and-overrides.rst
docs/concepts/index.rst
docs/concepts/package-settings.rst
docs/concepts/resolver-architecture.rst

🚧 Files skipped from review as they are similar to previous changes (7)

docs/concepts/architecture-overview.rst
docs/concepts/hooks-and-overrides.rst
docs/concepts/bootstrapper-architecture.rst
docs/concepts/package-settings.rst
docs/concepts/index.rst
AGENTS.md
docs/concepts/resolver-architecture.rst

📝 Walkthrough

Walkthrough

Adds architecture documentation for Fromager’s subsystems, bootstrapper phase pipeline, resolver/provider behavior, layered package settings, and hooks or overrides. The concepts index now links the new pages, while AGENTS.md requires architecture documentation to remain synchronized with related code changes.

Estimated code review effort: 2 (Simple) | ~15 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR adds resolver, hooks, and package-settings docs that go beyond the bootstrapper architecture requested by `#1247`.	Split those broader concept docs into a separate PR or link the issue that explicitly requests them.
Linked Issues check	❓ Inconclusive	The bootstrapper doc covers the phase flow and thread model, but the summary doesn't confirm module layout or WorkItem state coverage.	Add explicit coverage of src/fromager/bootstrapper/ layout and WorkItem state accumulation, or point to the sections that already cover them.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title concisely describes the main change: adding architecture overview docs.
Description check	✅ Passed	The description matches the PR and mentions both the docs update and the AGENTS sync rule.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/concepts/bootstrapper-architecture.rst`:
- Around line 1-6: Add a Sphinx `.. versionadded::` directive near the beginning
of the Bootstrapper Architecture document, using the release version that
introduced this new user-facing documentation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8cfd8523-ddb0-4830-af89-cd2473a0ddc7

📥 Commits

Reviewing files that changed from the base of the PR and between fdf55b3 and 129b2c1.

📒 Files selected for processing (3)

AGENTS.md
docs/concepts/bootstrapper-architecture.rst
docs/concepts/index.rst

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/concepts/index.rst`:
- Line 16: Update the Package Settings entry in the documentation to render the
PackageBuildInfo class name with reStructuredText inline code markup using
double backticks, while leaving the surrounding description unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 255e70a9-158c-4ad8-9a07-9a73317de426

📥 Commits

Reviewing files that changed from the base of the PR and between 129b2c1 and 47622cc.

📒 Files selected for processing (7)

AGENTS.md
docs/concepts/architecture-overview.rst
docs/concepts/bootstrapper-architecture.rst
docs/concepts/hooks-and-overrides.rst
docs/concepts/index.rst
docs/concepts/package-settings.rst
docs/concepts/resolver-architecture.rst

✅ Files skipped from review due to trivial changes (5)

docs/concepts/bootstrapper-architecture.rst
docs/concepts/architecture-overview.rst
AGENTS.md
docs/concepts/package-settings.rst
docs/concepts/resolver-architecture.rst

rd4398 · 2026-07-14T17:23:52Z

This looks generally okay. I will wait and do another pass once you address Doug's feedback.

Also add an AGENTS.md rule to keep the docs in sync when the architecture changes. Closes: python-wheel-build#1247 Co-Authored-By: Claude <claude@anthropic.com> Signed-off-by: Lalatendu Mohanty <lmohanty@redhat.com>

rd4398

This looks good and really helpful!

mergify · 2026-07-15T12:58:34Z

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

Queue this pull request

mergify · 2026-07-15T13:14:34Z

queue

⚠️ Configuration not compatible with a branch protection setting

Details

The branch protection setting Require branches to be up to date before merging is not compatible with draft PR checks. To keep this branch protection enabled, update your Mergify configuration to enable in-place checks: set merge_queue.max_parallel_checks: 1, set every queue rule batch_size: 1, and avoid two-step CI (make merge_conditions identical to queue_conditions). Otherwise, disable this branch protection.

LalatenduMohanty requested a review from a team as a code owner July 11, 2026 03:02

coderabbitai Bot reviewed Jul 11, 2026

View reviewed changes

Comment thread docs/concepts/bootstrapper-architecture.rst

LalatenduMohanty force-pushed the docs/bootstrapper-architecture branch from 129b2c1 to 8fed1d7 Compare July 11, 2026 03:06

LalatenduMohanty marked this pull request as draft July 11, 2026 03:07

LalatenduMohanty force-pushed the docs/bootstrapper-architecture branch from 8fed1d7 to 47622cc Compare July 11, 2026 15:18

LalatenduMohanty marked this pull request as ready for review July 11, 2026 15:20

LalatenduMohanty force-pushed the docs/bootstrapper-architecture branch from 47622cc to f2a037c Compare July 11, 2026 15:21

coderabbitai Bot reviewed Jul 11, 2026

View reviewed changes

Comment thread docs/concepts/index.rst Outdated

LalatenduMohanty changed the title ~~docs: add bootstrapper architecture overview~~ docs: add architecture overview docs Jul 13, 2026

LalatenduMohanty force-pushed the docs/bootstrapper-architecture branch 2 times, most recently from 9766874 to 5c2a741 Compare July 13, 2026 12:48

dhellmann reviewed Jul 13, 2026

View reviewed changes

docs: add architecture overview docs

ecdf478

Also add an AGENTS.md rule to keep the docs in sync when the architecture changes. Closes: python-wheel-build#1247 Co-Authored-By: Claude <claude@anthropic.com> Signed-off-by: Lalatendu Mohanty <lmohanty@redhat.com>

LalatenduMohanty force-pushed the docs/bootstrapper-architecture branch from 5c2a741 to ecdf478 Compare July 14, 2026 21:04

rd4398 approved these changes Jul 15, 2026

View reviewed changes

LalatenduMohanty merged commit cd7e127 into python-wheel-build:main Jul 15, 2026
39 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: add architecture overview docs#1250

docs: add architecture overview docs#1250
LalatenduMohanty merged 1 commit into
python-wheel-build:mainfrom
LalatenduMohanty:docs/bootstrapper-architecture

LalatenduMohanty commented Jul 11, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 11, 2026 •

edited

Loading

Walkthrough

❌ Failed checks (1 warning, 1 inconclusive)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rd4398 commented Jul 14, 2026

Uh oh!

rd4398 left a comment

Uh oh!

mergify Bot commented Jul 15, 2026 •

edited

Loading

Uh oh!

mergify Bot commented Jul 15, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

LalatenduMohanty commented Jul 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Jul 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

❌ Failed checks (1 warning, 1 inconclusive)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rd4398 commented Jul 14, 2026

Uh oh!

rd4398 left a comment

Choose a reason for hiding this comment

Uh oh!

mergify Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mergify Bot commented Jul 15, 2026

⚠️ Configuration not compatible with a branch protection setting

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

LalatenduMohanty commented Jul 11, 2026 •

edited

Loading

coderabbitai Bot commented Jul 11, 2026 •

edited

Loading

mergify Bot commented Jul 15, 2026 •

edited

Loading