Follow-up to #2873395: [meta] Add @internal to core classes, methods, properties

Problem/Motivation

https://www.drupal.org/core/d8-bc-policy#plugins
Particular plugin classes should not be considered part of the public API. References to plugin IDs and settings in default configuration can be relied upon however.

Some plugins that fall under this rule are being used by contrib. since they are useful to extend: CTools, Better Exposed Filters, MetaTag, Display Suite, Search API among others.

Proposed resolution

Add @internal tag to the Plugin classes

How to fix thisissue

  1. Read the description for a category in its issue
  2. Identify and confirm an example. Ask in IRC if unclear.
  3. Search core for the relevant category.
  4. Add @internal per the backwards compatibility policy.
  5. Reviewers should confirm that each @internal mention is appropriate for that category according to the policy.

Remaining tasks

Make the Patch and post it

User interface changes

None.

API changes

There should be no implicit API changes.

Comments

naveenvalecha created an issue. See original summary.

mradcliffe’s picture

mradcliffe
he/him
Primary language English
CreditAttribution: mradcliffe at Kosada commented

I think an exception needs to be made for particular views plugins.

It would be a pain in the butt to not be able to rely on ManyToOne or InOperator, which are valid views filter plugins, but really useful to extend as a contrib maintainer.

Perhaps there are some "base" views plugins that need to be marked as @api instead?

mradcliffe’s picture

mradcliffe
he/him
Primary language English
CreditAttribution: mradcliffe at Kosada commented

An alternative would be to add the useful code into traits, and then mark those plugins as @internal but provide the traits as @api.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.0-alpha1 will be released the week of July 31, 2017, which means new developments and disruptive changes should now be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

chenderson’s picture

chenderson CreditAttribution: chenderson commented
Issue tags: +Vienna2017

I am working on this at DrupalCon Vienna

yogen.prasad’s picture

yogen.prasad CreditAttribution: yogen.prasad commented

I am working on this issue at DrupalCon Vienna 2017

mradcliffe’s picture

mradcliffe
he/him
Primary language English
CreditAttribution: mradcliffe at Kosada commented

To expand on my suggestion above,

Basically, as I was reviewing the issue and looking at all the views plugins that we would mark @internal per policy, I thought back to how I developed contrib / custom modules, and how useful it was for me to extend off of views module's handler and plugin classes.

For instance I often found myself as a developer extending views_many_to_one and views_in_operator classes so that I did not need to rewrite some of the same functionality.

The same could be considered for some of the more basic filter, argument, and field plugins in views for Drupal 8.

I am not sure whether the correct approach is to make those classes a part of the API or mark them @internal in this issue and then follow-up to provide a way for contrib. and custom module developers to extend based on traits.

tedbow’s picture

tedbow
he/him
Primary language English
Location Ithaca, NY, USA
CreditAttribution: tedbow at Acquia commented

I do have the same concern as @mradcliffe. I am sure I would have done the same thing.

I took a quick look at Ctools and found that it is doing this, also Better Exposed Filters.
MetaTag
Display Suite
Search API, many times

I guess we could take this 2 ways.

  1. This just underscores the importance of having the @internal explicitly on all core plugins because even though it is documented that they are internal this is obviously not enough to get the message out.
  2. These plugins are really useful to extend and module developers are going to do it either way.

Not sure

mradcliffe’s picture

mradcliffe
he/him
Primary language English
CreditAttribution: mradcliffe at Kosada commented
Issue summary: View changes

In #2873696: Add @internal to core form classes, methods, and properties, I also brought it up as I was reviewing the patch, and we ended up not adding @internal to non-base form classes such as EntityForm and ContentEntityForm, but we did to EntityDeleteForm since there are base classes for confirmation forms.

We should probably explicitly add @api to these plugins since the policy still applies, and probably add it to those we did not add in #2873696: Add @internal to core form classes, methods, and properties.

tedbow’s picture

tedbow
he/him
Primary language English
Location Ithaca, NY, USA
CreditAttribution: tedbow at Acquia commented
Issue tags: +Needs subsystem maintainer review

Tagging this for subsystem maintainer review

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.0-alpha1 will be released the week of January 17, 2018, which means new developments and disruptive changes should now be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.7.x-dev

Drupal 8.6.0-alpha1 will be released the week of July 16, 2018, which means new developments and disruptive changes should now be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.7.x-dev » 8.8.x-dev

Drupal 8.7.0-alpha1 will be released the week of March 11, 2019, which means new developments and disruptive changes should now be targeted against the 8.8.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.8.x-dev » 8.9.x-dev

Drupal 8.8.0-alpha1 will be released the week of October 14th, 2019, which means new developments and disruptive changes should now be targeted against the 8.9.x-dev branch. (Any changes to 8.9.x will also be committed to 9.0.x in preparation for Drupal 9’s release, but some changes like significant feature additions will be deferred to 9.1.x.). For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 8.9.x-dev » 9.1.x-dev

Drupal 8.9.0-beta1 was released on March 20, 2020. 8.9.x is the final, long-term support (LTS) minor release of Drupal 8, which means new developments and disruptive changes should now be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 10.1.x-dev » 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch, which currently accepts only minor-version allowed changes. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.