Monolithic Git Transition FAQ

This page captures current contributor guidance for the BFDev monolithic Git transition. It complements the active BFDev Monolithic Git specification and keeps open questions explicit where the migration process is still being validated.

Note

This guidance reflects the current transition intent. Items marked as still being validated should be treated as working guidance rather than final cut-over policy.

How should the cut-over work?

The intent is a proactive setup period followed by a clean authoring cut-over:

• contributors clone and set up the monolithic bf-dev workspace before cut-over;
• contributors can experiment, branch, and validate locally in advance;
• once cut-over happens, new merge requests should be created from bf-dev, not from the downstream service repositories;
• bidirectional day-to-day authoring should be avoided because it increases sync risk and ambiguity.

What happens to open downstream merge requests?

The preferred cut-over state is zero open downstream merge requests.

If downstream merge requests still exist at cut-over time, they should usually be migrated or closed rather than merged later in parallel with the new authoring model. Manual migration may be possible with targeted Git history work, but there is not yet a standard documented process for doing that safely at scale.

What should I do with local branches, experiments, and stashes?

You do not need to delete old local work.

For work you want to preserve, the safest current path is to turn it into an explicit commit in the old repo, then move it into bf-dev with normal Git tools such as cherry-pick or by manually reapplying the change. Stashes may need extra cleanup because directory paths will differ between the old repo layout and the monolithic layout.

Older experimental stashes should be treated case by case. The transition does not require every historical stash to be migrated automatically.

Do I need the whole repository checked out locally?

Not necessarily. If you only need part of the monorepo working tree, use sparse checkout.

Sparse checkout is the main answer to concerns about editor load, local tooling scope, and bringing in repositories you do not actively work on. The current sizing measurements show sparse checkouts such as bf/manage-core at 38M, bf/manage-web at 119M, and bf/digital-twin at 314M; see Monolithic Git Sizing.

What if someone still pushes directly to a downstream repository?

Do not rely on reverse sync from downstream repos back into bf-dev.

The safer operating model is to prevent direct pushes and new merge requests in the old repos once the team has cut over. Accidental downstream changes are expected to be riskier and harder to reason about than normal bf-dev-first authoring.

How do rollbacks work?

From a deployment perspective, rollbacks remain repository-local: use the existing downstream repo and pipeline rollback path for the affected service.

From a source-control perspective, revert the relevant change in bf-dev and let the normal synchronization path propagate that reversion to the affected downstream repositories.

Where do merge conflicts get resolved?

After cut-over, contributor conflicts should be resolved in bf-dev.

The goal is to avoid a separate class of bf-dev versus downstream conflicts by stopping normal direct authoring in downstream repos. If two contributors change the same file or overlapping areas, that conflict is handled in bf-dev in the same way it would be handled in any other shared repository.

Can I keep different services on different revisions locally?

Yes, but it is less convenient than the current multi-repo model. The current guidance is to use git worktree when you need two revision combinations side by side.

For example, one worktree can hold the latest state while another holds an older revision for comparison or backwards-compatibility testing. This remains compatible with the transition goal of making worktree-based validation more normal.

How should commit messages work if one commit syncs to several downstream repos?

The synced downstream commit history will reflect the bf-dev authoring history, so a commit message may make most sense in bf-dev and less sense when viewed in isolation in one downstream repository.

If a contributor wants cleaner downstream history for a particular change, the practical option is to keep service-specific commits separate instead of relying on one fully squashed cross-service commit.

Will CI/CD become noisier or more fragile?

The intended model keeps downstream pipelines as the authoritative delivery path.

In the transition design, bf-dev automation is a lightweight synchronization layer that pushes the relevant directory changes downstream. The working assumption is that pipeline load is driven more by overall change velocity than by the monolithic authoring model itself.

Which repositories are in scope for the first migration?

The initial migration cohort is the current set of repositories listed in projects.txt.

The rationale is operational simplicity: one clean cut-over is easier to reason about than a mixed authoring model where only some repositories participate.

How much disk space do worktrees use?

git worktree is cheaper than maintaining several full clones because Git history is shared, but checked-out working files still take space.

The current measured upper bound is 11.8G for one full monolithic repository instance with host-installed dependencies. Each extra worktree adds about 606M of checkout size, and about 8.5G total if it also installs its own host dependencies. A base repo plus five additional fully provisioned worktrees comes out to 54.3G; see Monolithic Git Sizing.

If you install host dependencies separately in each worktree, those dependencies are duplicated. If you use Docker-based workflows, image layers and container infrastructure are reused, which makes the multi-worktree setup comparatively lighter.

Is this the final architecture?

No. This transition is an authoring-repository change, not a runtime consolidation decision.

The current direction treats monolithic bf-dev as a lightweight layer over the existing service topology so the team can simplify authoring first. It may make later service or pipeline consolidation easier, but it does not itself commit the platform to that future state.

What mental model should I use inside the monolithic repo?

Think of service directories the same way you already think about major modules inside a large codebase: they are still bounded areas with their own responsibilities, but they now live in one authoring surface.

The change is mainly about reducing Git and review friction, not about pretending the underlying services no longer exist.