Drupal core frontend backwards compatibility (BC) policy

This document defines what parts of the frontent Drupal code base are considered stable and reliable APIs, and which parts module and theme developers should not rely on. Drupal core uses Semantic Versioning for managing releases.

For changes to anything other than render arrays, themes, markup, CSS, and JavaScript, refer to the backend backwards compatibility policy.

# 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. This means alter hook implementations may need to be updated.

# Themes, markup, templates, and CSS

We will change the markup and CSS that core generates for user interface and theme improvements. Core themes that are internal may change. Themes that are internal are indicated by a comment theme info.yml file.

The Stable base theme is considered public API, with stable templates, markup, and CSS, so themes needing BC support should extend that.

# Image assets

Image assets in core's modules and /misc folder are considered internal and may change. We will provide backwards compatibility for images used by our Stable base theme. Themes requiring backwards compatibility should extend one of those themes.

# Variables passed to preprocess functions

The content of variables passed to preprocess functions may change in similar ways as render arrays. Since other preprocess functions may also make those changes, preprocess implementations should be written in such a way as to account for the change or be prepared to update