Upgrade Guide: 2.x to 3.x

Are there breaking changes in the update to 3.x?

There wasn't anything specifically called out in the release notes or the successive alpha and beta releases:

https://www.drupal.org/project/components/releases/3.0.0-alpha1 →
https://www.drupal.org/project/components/releases/3.0.0-alpha2 →
https://www.drupal.org/project/components/releases/3.0.0-alpha3 →
https://www.drupal.org/project/components/releases/3.0.0-beta1 →
https://www.drupal.org/project/components/releases/3.0.0-beta2 →
https://www.drupal.org/project/components/releases/3.0.0-beta3 →

Here is a link to the diff:

https://git.drupalcode.org/project/components/-/compare/8.x-2.4...3.0.0-...

From that I spot the following breaking changes, which depending on your use of the module, may or may not be an issue:

• componets.info service name changed to components.registry
• ComponentsLoader::__construct arguments changed. Only a problem if you're extending the class, otherwise if your using service (components.twig.loader) from the container, should be fine.
• ComponentsLoader protected members changed. Only a problem if you're extending the class.
• ComponentsLoader::checkActiveTheme public method removed.
• ComponentsLoader::addPath public method removed.
• ComponentsLoader::prependPath public method removed.
• Dropped support for Drupal 8

I work on a very large codebase with heavy componets module use. None of these breaks apply. Also note that there are 3.x version specific notes throughout the guide. https://www.drupal.org/docs/contributed-modules/components →

I came across 🐛 Templates not found in some theme directory configurations RTBC today when upgrading to 3.x. It doesn't seem to be an intentional breaking change, but something to be aware of, since it seems other sites are reporting similar errors.

I ran into an issue after upgrading from 2.x to 3.x on a project. The site was throwing an error similar to "Template xxx is not defined..." I finally figured out the project was still using the older 1.x API which was deprecated in 2.x, and removed in 3.x. Hopefully, this helps someone else.

More details can be found at https://www.drupal.org/docs/contributed-modules/components/registering-t... → , and https://www.drupal.org/docs/contributed-modules/components/registering-t... → .