> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Change one thing at a time

> Apply the change-one-thing-at-a-time discipline to Bazel migrations so regressions are bisectable and bazel build --subcommands can verify each step.

Build system changes can cause subtle regressions, where cause and effect are at a distance, and the developer encountering the problem and the build system engineer who caused it are totally unfamiliar with the domain of the other. This makes it hard to diagnose problems.

Just like a `git bisect` workflow, a sane, linear history of events makes it much easier to reason about what happened.
Based on the delta of what changed, you can make assertions about what is the possible blast radius, and whether that can explain the problem.

Therefore, try to change only one thing at a time.
Use pre-factoring changes to the old build system to do things like break up a cycle in the dependency graph (but avoid such code changes if they're not load-bearing for Bazel migration, see "don't change the code" below).
Use post-factorings to make related cleanups you noticed during the migration.
Resist the urge to combine these at all costs!

One ideal outcome from this principle: you can use `bazel build --subcommands` to see the flags passed to some tool X, then compare with how that tool was called by the legacy build system, and any differences should be intentional and required by this migration step.