Problem/Motivation

This is a meta issue to organize child issues for applying the Drupal 8 core backwards compatibility policy: https://www.drupal.org/core/d8-bc-policy.

Proposed resolution

Done when all child issues are complete.

Each child issue should apply to each of the following areas on the policy page:

Novice categories that can be done quickly

  • Tests
  • Controllers and Form classes
  • Plugins
  • Entity handlers
  • Param converters
  • Access checkers
  • Event Subscribers
  • JavaScript classes
  • Constructors for service objects
  • Constructors for plugins
  • Constructors for controllers (Is this duplicated by the controller class task above?)
  • Protected methods
  • Protected properties
  • Public properties
  • Public methods
  • Underscore-prefixed functions and methods

Categories that need more time and review

  • PHP classes
  • The Installer: install global functions, install tasks, and classes.
  • Hook implementations

How to fix each child issue

  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.
    • Using PHPStorm's subclass hinting feature. Go to relevant base class (e.g.core/lib/Drupal/Core/Form/FormBase.php) and search for all usages.
    • Add @internal to subclasses that are not base classes. If there is no DocBlock, create one.
    • Add @internal per the backwards compatibility policy.
    • Reviewers should confirm that each @internal mention is appropriate for that category according to the policy.

    Remaining tasks

    • Create child issues. Each issue should:
      • Contain the description of the category in the issue description
      • A link to the this issue and a link to the backwards compatibility policy: https://www.drupal.org/core/d8-bc-policy
      • Tag issue as Novice if the category is listed in the Novice section above.

    User interface changes

    None.

    API changes

    There should be no implicit API changes.

    Comments

    mradcliffe created an issue. See original summary.

    mradcliffe’s picture

    mradcliffe
    he/him
    Primary language English
    commented
    Category: Task » Plan

    The meta issue should be a plan and not a task because it is not actionable.

    mradcliffe’s picture

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

    Adding a bit of description for how to approach each issue so that the child issues can link to the meta issue.

    mradcliffe’s picture

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

    @xjm gave a review of the issue so far.

    1. We should be explicit in the descriptions of the categories in the child issues and add that to the instructions for creating child issues and for fixing child issues.
    2. Split into novice / not-novice
    3. Find and identify an example of the change for novices so that we can confirm what is done.

    I added hook implementations as a non-novice task for now because it is not technically in the policy yet, but it should be according to @catch and @xjm.

    The controller constructor and controller classes may be duplicate. Shouldn't controller class @internal apply to all methods as well?

    heddn’s picture

    heddn
    Primary language English
    Location Nicaragua
    commented

    Adding at least a single example sub issue would be super helpful. We could use it as a clone then.

    nvexler’s picture

    nvexler commented

    @heddn I'd totally agree with an example being useful. I'm currently working on https://www.drupal.org/comment/12060517/ and could use an example.

    mradcliffe’s picture

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

    Added @nvexler's tips to the issue summary.

    nvexler’s picture

    nvexler commented
    Issue summary: View changes

    Made some minor fixes to the instructions. Right on @mradcliffe for adding the instructions I wrote up :). Props also to @naveenvalecha since it was his idea in the first place.

    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.

    webchick’s picture

    webchick
    she/they
    Primary language English
    Location Vancouver 🇨🇦
    commented

    I have perhaps what is a very silly question but... if we don't want things to be part of the public API, why are we indicating this by adding specially-formatted comments, and not by explicitly declaring those things as private like is standard in other OO code in other languages (and shows up in standard IDEs, etc.)? I guess cos it would break BC to do it now? Something to do in 9, potentially?

    mile23’s picture

    mile23
    Primary language English
    Location Seattle, WA
    commented

    The point of the annotation is to show that even if a method is public, it isn't necessarily part of the API. So if you call something marked @internal, your code might break later.

    It's similar to @deprecated, except you should think of it as already gone. :-)

    Also: private only says that the method can't be called from another class context, not that the code is considered an implementation detail of an API. And, for some reason Drupal culture says we can't use private in core anyway.

    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.

    joachim’s picture

    joachim commented

    Given that https://www.drupal.org/core/d8-bc-policy still says that it's not yet official policy, is it wise to go ahead with marking things as @internal in the code? Shouldn't we agree on the policy first?

    xjm’s picture

    xjm
    she/her
    Primary language English
    commented

    @joachim: Sorry, missed that comment back when you posted it. In practice, the policy is official and has been for years. I'll reword that part of the doc. Edit: Actually it looks like I already fixed the doc several months ago, but did not document that here. :)

    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.

    Version: 11.x-dev » main

    Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

    Read more in the announcement.