Getting Started

Start with src/AcmeBundle.php and the new getPath() override. This is the only runtime code shown in 4.0; the rest is a directory/symlink compatibility recipe.
Release 4.0 is primarily a documentation and structure update. No new services, configuration keys, or public APIs are introduced in the notes.

Minimal setup for a mixed-version bundle:

Symlink the canonical root-level directories into it:

cd src/Resources
ln -s ../../config/ config
ln -s ../../public/ public
ln -s ../../translations/ translations
ln -s ../../templates/ views

Override getPath() so Symfony resolves the correct bundle root:

use Symfony\Component\HttpKernel\Kernel;

public function getPath(): string
{
    return Kernel::VERSION_ID >= 40400 ? \dirname(__DIR__) : __DIR__;
}

First use case: migrating a bundle from the legacy src/Resources/ layout to root-level config/, public/, translations/, and templates/ while still supporting older Symfony versions.
Look at the upstream mixed branch for a working example before applying the pattern to your own bundle.

Implementation Patterns

Keep canonical resources at the bundle root for modern Symfony versions: config/, public/, translations/, and templates/.
Expose legacy paths only through symlinks under src/Resources/. Avoid duplicating files; the symlink becomes the compatibility layer.
Use Kernel::VERSION_ID >= 40400 as the switch. Symfony 4.4 introduced the root-level bundle structure, so the boundary should be tested explicitly.
For older Symfony versions, getPath() must return __DIR__ so @AcmeBundle/... resource references continue to resolve under src/Resources/.
For Symfony 4.4+, getPath() returns \dirname(__DIR__) so Twig, translations, config, and public assets resolve from the bundle root.
Keep a CI matrix covering both sides of the compatibility boundary—for example Symfony 4.3/4.4 and the current 5.x/6.x line. The symlink layout is only safe if both paths are exercised.
Treat the symlinks as part of the package contract. They should be committed to Git and preserved by packaging/deployment tooling.
If you also maintain Laravel packages, the analogue is keeping one canonical resource directory and using service provider loaders (loadViewsFrom(), loadTranslationsFrom(), mergeConfigFrom()) instead of duplicating resources. The 4.0 recipe itself is Symfony-specific.
Use the pattern when maintaining a bundle across major Symfony upgrades, not as a permanent replacement for dropping old framework versions.

Symlinks are the main failure point. Windows checkouts, ZIP archives, Docker build contexts, and some deployment tools may dereference or drop them. Verify the layout after packaging.
Git must preserve symlinks. Check core.symlinks on Windows and confirm the symlinks appear as links in CI.
Composer archives and export-ignore rules can exclude or flatten symlinked directories. Test the installed package, not just the working tree.
getPath() affects all @AcmeBundle/... resource resolution. A wrong return value can break templates, translations, routing, and config loading at once.
Clear the Symfony cache after changing bundle paths or symlink targets. Stale container/Twig caches can mask path errors.
Test the exact version boundary (Kernel::VERSION_ID 403xx vs 40400) rather than assuming the constant behaves as expected.
PHPStan, Psalm, and some IDEs may not follow symlinks reliably. Add explicit excludes or include the canonical root paths in static analysis.
Debug with bin/console about, debug:container, debug:twig, and a quick dump of $bundle->getPath() if resource lookup fails.
The primary extension point is Bundle::getPath(). Avoid adding custom path-resolution logic elsewhere; centralize compatibility there.
The release notes do not indicate runtime breaking changes, but the 4.0 label and layout guidance warrant a full regression test on both supported Symfony layouts before upgrading.