Experimental modules and themes in Drupal core

Drupal 8 core introduced the concept of experimental modules. These are modules that are provided with Drupal core for testing purposes, but that are not yet fully supported. Experimental modules are included in the Core (Experimental) package on the Extend page of a Drupal site (/admin/modules).

What is the purpose of experimental modules and themes?

Experimental extensions, modules or themes, provide new features that may be added to core. They are available so that they can be tested by the community in a wide variety of situations.

They have a change policy different from the rigorous core change policy. The change policy allows for faster development. For example, an experimental extension can change between patch releases. Other core extensions can not change between patch releases. The section on experimental module versions below describes how they may change in more detail.

Who should use experimental modules or themes?

Experimental modules and themes allow site builders and contributed project authors to test out functionality that might eventually be included as a stable part of Drupal core. Use them at your own risk. See the experimental module version information below to help you evaluate whether you should test the module. Also keep in mind that the experimental module might be removed from Drupal core if it turns out to not be a good fit.

Experimental module and theme versions

Experimental modules and themes have separate stability from the Drupal core release that contains them. The current experimental modules and themes in core are:

Experimental modules that do not meet their followup requirements may be removed from core at committer discretion. See the release cycle overview for current release cycle dates.

Definitions for the different stability levels of experimental modules

Alpha (e.g. 9.y.x-alpha)

• Alpha experimental modules are still under development, but available for initial testing. They may include bugs, including security or data integrity issues.
• Alpha modules are not subject to the restrictions on allowed changes and may have backwards compatibility (BC) breaks. Developers should not rely on their APIs.
• No upgrade path is provided from alpha versions. To resolve issues for the module, uninstall and reinstall it (backing up any data).
• If an alpha experimental module does not reach beta-level stability before the alpha phase of a given minor release (e.g. 8.5.0-alpha1), it will be left in the new development branch (e.g. 8.6.x), but removed from the release branch (e.g. 8.5.x) before the alpha release is tagged. As of Drupal 8.5.x, we will no longer ship alpha-level experimental modules in stable releases of Drupal 8.

Beta (e.g. 9.y.x-beta)

• Beta experimental modules are considered API- and feature-complete for the minimum viable product. Some early adopters may begin using beta experimental modules on development sites, but should be aware that they are not yet fully supported and may contain bugs.
• Developers can begin using beta modules' APIs, but should be aware that some things may still change to address bugs. Beta modules are mostly subject to the beta allowed changes policy, with some feature additions, UI and string changes, internal API changes, and other disruptive allowed changes sometimes backported to patch releases for earlier testing and feedback. Such backports should have a release manager's signoff if the disruption is non-trivial.
• Beta modules generally follow the core deprecation policy and should not have BC breaks for public APIs except in unusual circumstances.
• An upgrade path will be provided from beta versions, but be aware it may contain critical bugs.
• Once the module or theme is in a tagged release of core, security issues with it should be reported privately using the normal security reporting process. They have security coverage because they have been included in a tagged stable release of core, which has security coverage.

Release candidate (e.g. 8.y.x-rc)

• Release candidate (RC) experimental modules are essentially stable and may be release-ready, although some changes might be made to address critical bugs.
• RC modules are subject to the RC allowed changes policy.
• Upgrade paths are provided from release candidate versions.

Stable core modules

Once an experimental module is judged stable, the module will be moved out of the Core (Experimental) package, and its version number and allowed changes will be the same as Drupal core's. Experimental modules and themes may only become stable modules in minor or major releases. Not all experimental modules will necessarily become stable core modules.

When should I propose an experimental module or theme?

If your proposed feature will require multiple issues to meet the quality requirements for stable functionality, or if implementing the feature against stable functionality would be disruptive, consider creating it as an experimental module. Start with opening an Idea issue and get feedback from product and framework managers before starting to write code to avoid wasting time. See How are initiatives chosen and approved. While your module proposal may not be an initiative in itself, a new module is substantial enough that you don't want to spend time building it as a core patch without first figuring out if it has a chance of getting accepted.

Once the ideas process is completed, experimental modules are proposed as core issue patches, like any other feature request.

What requirements must an experimental module or theme meet?

Experimental modules are not subject to the same rigorous quality standards as stable Drupal core modules and do not yet need to meet all the Drupal core gates. They can be added with known architectural issues, imperfect coding standards (so long as they do not fail automated checks), minimal UIs, outstanding issues, etc. However, to add an experimental module, there are minimum initial requirements and followup requirements:

1. No known security or data integrity issues, including security and data integrity for revision and translation support.
2. No disruption or regression to stable functionality (including being able to remove the experimental module without lasting disruption).
3. Functional test coverage for the primary usecase, with no test failures in HEAD.
4. Basic API documentation for the minimum requirements, an initial change record draft for the addition of the module, and a plan for completing more comprehensive documentation in the codebase and handbook.
5. Ideas/prototypes for user interfaces that are planned and minimally validated.
6. Wherever possible, extension names, namespaces, plugin IDs, etc. should be valid and match the intended final names, to avoid unnecessary upgrade path issues. (This includes whether it makes sense for the functionality to exist in a separate module at all.)
7. Resolution of other critical issues that maintainers identify as hard blockers.
8. A separate module roadmap ("plan" issue) documenting followup steps for outstanding work, including:
   • Followups to meet the core gates.
   • Followups to address concerns with the experimental UI and architecture, and iterate on them as needed.
   • Any other issues identified during planning and review.

9. A timeframe for completing the remaining work (typically two minor releases), a plan for addressing followups, and roughly which followups must be completed to keep the module in core. Followups should be grouped according to whether they must, should, or could be a part of the module's initial stable release.

   For must- or should-have followups that require numerous screenshots, detailed code snippets, or in-code @todos, or for those that need to be completed soon, an explicit issue should already be filed and referenced. In other cases, a bullet should be added to the roadmap issue's summary, for example:

   Must-have

   • [#NNNNNNN]
   • Usability review of UI texts

   Should have

   • [#NNNNNNN]
   • Theme system maintainer review for theme implementations

When reviewing proposed experimental modules, consider whether your feedback is part of these minimal requirements, or whether it should instead be followup work as part of making the experimental module stable. If it does not need to block commit, post a followup issue on the roadmap instead of commenting on the initial patch. (Also see the approval process for initiatives.)

How do experimental modules and themes become stable?

Alpha experimental modules and themes can be added to the development branch at any time prior to the alpha deadline for the minor release. An existing experimental module may be marked as beta, release candidate, or stable at any time prior to the beta deadline.

Before the alpha phase for each minor release, core committers review the status of all experimental modules and themes in core and work with the modules' maintainers to reassess their stability and whether they are still on track to become stable modules. In order for the module to be moved out of the Core (Experimental) packaged and be considered a stable part of core:

• No known security, data integrity, or upgrade path issues.
• All the required followup issues on the approved roadmap must be finished.
• All core gates should be satisfied.
• The module should be considered feature- and API-complete by the maintainers.
• Most major bugs and any critical issues identified during real-world testing should be resolved.

When would an experimental module or theme be removed from core?

Not all experimental modules may graduate to stable status. The following situations may lead to the experimental module being removed from core:

• The technology used is found to not be a match to implement the feature desired.
• A better solution in core supersedes the module.
• Sufficient progress is not being made on the required followup work within the timeframe indicated on the module's roadmap.

This list is not exhaustive.

When an experimental module is removed from core, it may be made available as a contributed module instead.

If an experimental module or theme has already been included as a beta release or higher within a stable release of core, but it's later determined that the module should be removed, we will begin by marking the module hidden, deprecating its code, and adding a requirements message clarifying the status (to reduce disruption and avoid fatal errors for sites that tested the module.)

How can experimental modules add core APIs?

When an experimental module wants to add API to a core namespace before it reaches beta stability and risks to be removed from the next release it needs to add the classes to its own namespace so that everything can be removed together.
In order to minimize disruption for contrib modules that are building features against the experimental module, we would like the module to be able to use the class alias feature of PHP to alias the classes into the core namespace.
This will allow module developers to add a dependency on the experimental module, but code against core namespaces so that when the module moves from experimental into the core namespace, they don't have to update their code.

• Add the classes to a namespace that maps closely to its future core namespace. For example Drupal\config_environment\Core\Config\StorageTransformEvent for a class that will be Drupal\Core\Config\StorageTransformEvent.
• Add a class alias at the top of the .module file with errors suppressed. For example @class_alias('Drupal\config_environment\Core\Config\StorageTransformEvent', 'Drupal\Core\Config\StorageTransformEvent');
• Add a comment with a @todo to remove the class alias and the issue number.
• (Optional) Add a comment explaining why we are doing the class aliases. for example:
  

  // Set class aliases for the classes that will go into core when we are in beta.
  // See the experimental modules policy https://www.drupal.org/core/experimental
  // @todo: remove class aliases in #issue-number
  

Past experimental modules and themes

Stable modules and themes

The following modules were developed with the experimental development process and became stable core features. (Not all core features are developed with the experimental process.)

Deprecated or removed

The following modules were included as experimental modules in a previous core release, but did not become a part of stable core and are no longer being developed as experimental modules.