Problem/Motivation
See #2116841: [policy] Decide what the Drupal Public API should be and how to manage it.
Proposed resolution
Get the draft policy below finalised and added to either the handbook or api.drupal.org or both.
Original draft by Jess and Larry at DrupalCon Austin.
Open sub-issues for things not covered.
Drupal 7 backport policy: https://drupal.org/node/1527558
This document defines what parts of the Drupal codebase are considered stable and reliable APIs, and which parts module and theme developers should not rely on. The goal is to provide a greater degree of clarity about what constitutes Drupal's APIs and what constitutes implementation details.
Minor releases vs. patch releases
Drupal core patch releases (8.y.z) will contain security fixes and bug fixes only. No new functionality will be introduced, and no refactoring will be included except that necessary as part of a security or bug fix. See the Drupal 7 backport policy for more information.
Minor releases (8.x.0) may include non-API-breaking refactoring, new features, or enhancements of existing features. In such cases the core team will work to ensure that these enhancements do not alter the existing public-facing API of core systems.
Necessary security hardening takes priority over API stability.
We will make every effort to address security issues without affecting the public API. However, in some cases it will not be possible to address a security vulnerability without an API change. In such cases we will work to minimize the scope of the API change and document it thoroughly.
Backward compatibility (BC)
When we do make changes in either minor or patch releases, we will make reasonable efforts to provide a backward compatibility layer (BC).
We will take reasonable efforts to not break code that developers may be relying on
While core developers may change implementation detail code between minor versions when it is necessary to make an improvement, we will make a reasonable effort to minimize these changes.
The following parts of the code base should always be treated as internal and are not guaranteed to not change between minor versions:
- The database schema for core modules
- While the database query API and schema API itself are stable, the schema of any particular table is not. Writing queries directly against core tables is not recommended and may result in code that breaks between minor versions.
- Render arrays (including form arrays)
- While the render and form APIs themselves are stable, the exposed data structures used to build and cache pages and forms are not. We will change these structures where necessary to make usability improvements or add features in minor versions.
- Markup, templates, and CSS
- We will change the markup and templates for specific user interfaces for usability or feature enhancements, but we will avoid broad changes to markup or CSS that will affect more than one user interface.
- Tests
- The contents of automated tests provided by core modules are never considered part of the API. While the testing framework itself may be treated as an API individual test classes are always internal.
- Controllers
- Core modules contain many route controllers that are bound to individual routes. These controllers are not part of the API of the module unless specifically marked with an @api tag on the method or class.
- Strings
- User-facing strings may change between minor releases. However, any significant change to strings must be committed at least two months prior to an expected minor release to allow localization teams time to update translation sets.
- Constructors for service objects, plugins, controller
- The constructor for a service object (one in the container), plugin, or controller is considered internal unless otherwise marked, and may change in a minor release. These are objects where developers are not expected to call the constructor directly in the fist place. Constructors for value objects where a developer will be calling the constructor directly are excluded from this statement.