Merge Up

2c. Run tests for affected packages

Extract package and bridge names from changed files:

git diff --name-only HEAD~1..HEAD

Paths look like src/<NAME>/..., or src/<NAME>/src/Bridge/<BRIDGE>/... for a bridge, which has its own composer.json and test suite. Deduplicate, then run the tests from each directory. Each package has its own vendor/ and the branches pin different dependencies, so update it first:

(cd <DIR>; composer update; symfony php vendor/bin/phpunit)

When src/<NAME>/assets/ changed, also run that package's JS tests: (cd src/<NAME>/assets; pnpm run test:unit).

Ignore files outside these directories (root configs, .github/, etc.): they don't have package-level test suites.

Read the whole summary line, not just the exit status: a suite can end with Tests: N, Failures: 1 or abort on a Fatal error well before any FAILURES! banner, and ANSI colour codes sit in front of those words, so a check anchored to the start of a line reports a red run as green.

If tests fail or report PHPUnit deprecations (2.x runs phpunit-bridge, 3.x PHPUnit 11/12), first check whether the failure is pre-existing. Cheapest test first: if the merge did not touch the failing area, it did not cause the failure.

git diff --name-only HEAD~1..HEAD -- <path of the failing test or the code it covers>

Only when that is inconclusive, run the test on the TARGET before the merge (git checkout HEAD~1, run, git checkout <TARGET>). Beware a CI baseline as evidence: a branch tip that has not been pushed in a while keeps an old green run, and CI installs dependencies fresh on every run, so a release made in between can turn a suite red with no commit to blame.

Only fix failures introduced by the merge:

1. Analyze and fix the code, including any PHPUnit deprecation notices.
2. Commit the fix: [<ComponentName>] Fix merge conflict resolution.
3. Re-run failing tests until green and deprecation-free.

Report any pre-existing failures to the user without attempting to fix them.

Failures a local run cannot show

A local composer update installs the sibling UX packages a package requires (e.g. symfony/ux-twig-component for LiveComponent) from Packagist, at their released version. CI first runs .github/build-packages.php, which rewrites every composer.json to use the sibling packages from the checkout. A merged test that relies on a sibling change from the same merge can therefore fail locally and pass in CI. To reproduce CI, run php .github/build-packages.php before composer update, and restore the rewritten composer.json files with git checkout -- '*composer.json' before committing anything.

CI also runs a lowest-dependencies job and jobs pinned to specific Symfony versions, while a local run gets the newest versions the constraints allow. An assertion pinned to a Symfony component's exception message can break when a newer release appends to it: assert the part that identifies the failure and leave the tail free (drop a trailing ., or use expectExceptionMessageMatches()), and fix it on the oldest branch that has the test so the cascade carries it up.

Before writing a CI failure off as flaky, check that the group meant to exclude it is actually excluded: the jobs pass --exclude-group skip-on-lowest and --exclude-group transient-on-windows, and on 3.x the group has to be an attribute, since PHPUnit 11 deprecates doc-comment metadata and PHPUnit 12 ignores it.

2d. Ask for confirmation before pushing

Show:

Merge: <SOURCE> -> <TARGET>
Affected: <package list>
Tests: all passing

Commits since upstream/<TARGET>:
git log --oneline upstream/<TARGET>..<TARGET>

Ready to push? (yes / no)

Wait for confirmation. The user may make changes themselves before confirming.

2e. Hand over the push and continue

The user pushes. Print the command for them to run:

git push upstream <TARGET>

Wait until they report it done. If the push fails, stop and let them handle it.

Print "✓ <SOURCE> -> <TARGET> done." and continue to the next pair.

Final summary

All merges complete:
  2.x -> 3.x  ✓

Gotchas

• CHANGELOG.md conflicts are the most common; entries must be kept from both sides, never dropped.
• A merge can introduce test failures even without conflicts, because behavior from the older branch may be incompatible with newer code. Always run tests.
• A clean (no-conflict) merge still needs verification, not just a commit: auto-merged test metadata (docblock vs attribute), a rebuilt dist/, and CI version pins can each be wrong even when git reports no conflict.
• Some packages have slow test suites. Only run tests for packages with changed files, not the entire project.
• When the user states a constraint about the merge as a whole, it applies to the entire merge diff, not only to the files git flagged as conflicting. Grep the whole diff for the concept and check every hit, including other packages and their bridges. Auto-merged hunks are where a constraint like that gets lost silently.
• Resolving only the conflicted hunk of a file leaves the rest of it auto-merged. When the two sides restructured the same file, read the resolved file end to end before staging it, otherwise it can end up declaring the same thing twice or dropping a return.

Error handling

• Never force-push or rewrite history.
• Never use --no-verify on commits.
• Never git add -A (or git add .) while resolving: it sweeps the user's untracked working files into the merge commit. Stage the files you resolved, by name.
• Never git reset in the middle of a merge: it deletes .git/MERGE_HEAD, and the commit that follows records a single parent, silently turning the merge into a squash.
• Never auto-recover from a failed git pull. Stop and hand control back to the user.
• Never parallelize the cascade or run branches concurrently (e.g. via subagents): each merge depends on the previous one and shares the git working tree. Run strictly oldest to newest, one at a time.