Problem/Motivation

Breaking changes starting from 3.x may make it quite hard to perform an upgrade. Let's have proper docs with helpful information:

Remaining tasks

1. Write documentation to upgrade.
2. Get maintainer's review.
3. Add the new page to the guide.

Comments

sokru created an issue. See original summary.

m4olivei’s picture

m4olivei
he/him
Primary language English
Location Grimsby, ON
commented

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

marcoscano’s picture

marcoscano
Primary language Portuguese, Brazil
Location Barcelona, Spain
commented

I came across #3368589: Trim the right-hand slash on namespace paths 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.

nmangold’s picture

nmangold commented

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....

johnalbin’s picture

johnalbin
they/他
Primary language English
Location Taipei, Taiwan
commented
Status: Active » Closed (works as designed)

Let's have proper docs with helpful information:

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.

Yep. The docs were already written when Components 2.0 was released. Whoever updated your website from Components 1.0 to 2.0 screwed up. I'm sorry you are now having issues when upgrading to 3.0. But you could have read them then and you wouldn't have broken the site when 3.0 was released.

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.