Drupal Release: 10.3.0

TL;DR

Drupal 10.3.0 introduces significant enhancements to the CMS platform with a focus on improved user experience, accessibility, and developer tools. The release features the new experimental Navigation module, which provides a modern, accessible navigation system, along with workspace improvements for content management. Security has been strengthened with CSRF protection for user logout and PHP 8.3 is now recommended. The release also introduces the new Recipes API as an experimental feature, allowing for easier site setup and configuration. Performance optimizations, particularly in asset handling and caching, make this release faster and more efficient. This update represents an important step forward in Drupal's evolution with numerous bug fixes and improvements to prepare for future development.

Highlight of the Release

• New experimental Navigation module providing a modern, accessible navigation system
• Improved workspace management with APIs for workspace-safe forms and actions
• Introduction of the experimental Recipes API for easier site setup and configuration
• Security enhancement with CSRF protection for user logout
• Performance improvements in asset handling and caching
• PHP 8.3 is now recommended
• Conversion of plugin discovery to PHP attributes instead of annotations
• Better accessibility for keyboard users and screen readers
• Reduced layout shifts for a more stable browsing experience

Migration Guide

Preparing for the Update

Before updating to Drupal 10.3.0, ensure you:

1. Back up your site - Create a complete backup of your database, code, and files
2. Update to PHP 8.3 - While not required, PHP 8.3 is now recommended for Drupal 10.3.0
3. Check module compatibility - Verify that your contributed modules are compatible with Drupal 10.3.0
4. Review deprecated code - If you have custom modules, check for usage of newly deprecated functionality

Handling Deprecated Functionality

Several components have been deprecated in this release:

• Statistics module is now deprecated for removal in Drupal 11.x
• Contextual module has been updated for removal in Drupal 12.0
• shepherd.js has been deprecated
• Drupal\locale\Locale class and its one method are deprecated
• Various user module deprecations have been updated

If your site or custom modules use these components, plan to update your code accordingly.

PHP Attribute Migration

If you have custom plugins that extend any of the following systems, consider migrating from annotations to PHP attributes:

• Field Type plugins
• Layout plugins
• CKEditor 5 plugins

While annotations will continue to work for now, attributes are the recommended approach moving forward.

jQuery Event Replacements

Several jQuery events have been replaced with native JavaScript CustomEvents:

• dialogContentResize jQuery event has been replaced with a CustomEvent
• Various other jQuery-based functionality has been refactored to use vanilla JavaScript

If you have custom code that relies on these jQuery events, update it to use the new CustomEvent equivalents.

Testing Updates

If you maintain tests for your custom modules:

• Update data providers to use static methods for PHPUnit 10 compatibility
• Review tests that might rely on UID1's super user behavior
• Update any tests that use deprecated PHPUnit functionality

Upgrade Recommendations

Recommendation Level: Standard Upgrade

Drupal 10.3.0 is a feature release that introduces new experimental modules and APIs while fixing numerous bugs and improving performance. While it doesn't contain critical security fixes that would necessitate an immediate upgrade, the improvements in security, performance, and functionality make it a worthwhile update for most sites.

Who Should Upgrade Immediately:

• Sites that would benefit from the new Navigation module capabilities
• Developers working with workspaces who need the new workspace-safe APIs
• Sites experiencing any of the specific bugs fixed in this release
• Development teams wanting to start using the new Recipes API

Who Can Wait:

• Production sites that require extensive testing before upgrades
• Sites with complex custom modules that might need updates for compatibility
• Sites that rely heavily on contributed modules that haven't been tested with 10.3.0

Upgrade Path:

1. For sites on Drupal 10.2.x, a direct upgrade to 10.3.0 is recommended
2. For sites on earlier versions of Drupal 10, update to the latest 10.2.x release first, then to 10.3.0
3. For sites on Drupal 9.x, consider updating to Drupal 10.0.x or 10.1.x first, then proceed to 10.3.0

Testing Recommendation:

As with any minor version update, thorough testing in a staging environment is strongly recommended before updating production sites. Pay particular attention to custom modules and any functionality that interacts with the areas that received significant changes, such as workspaces, navigation, and file uploads.

Bug Fixes

User Interface and Experience Fixes

• Fixed issue where newly added menu links were invisible until published
• Fixed custom blocks with Layout Builder not using the front-end theme
• Fixed toolbar.js error: "Cannot read properties of null (reading 'style')"
• Fixed Views UI action buttons creating janky layout shift on page load
• Fixed tab highlights for tabs with multi-line text
• Fixed focus states on mobile second-level navigation items in Olivero theme
• Fixed shortcuts menu flickering when the page is loaded
• Fixed CKEditor 5 dialog appearance issues

Layout and Display Fixes

• Fixed Claro disabled form labels having too low color contrast
• Fixed Claro details component not having the right class
• Fixed Claro dropbutton items adding large gap of white space
• Fixed Olivero content shift on page load
• Fixed "Skip to Main" link placement and functionality
• Fixed BigPipe injecting Local Actions block creating large layout shifts

Entity and Content Management Fixes

• Fixed changing a display's machine name while an attachment exists breaking Views
• Fixed updates to an entity's URL alias not reflecting on corresponding local tasks
• Fixed FileItem translations not being synchronizable
• Fixed handling of invalid compressed ajax_page_state
• Fixed uploading a file to media library flushing theme registry

Security and Access Fixes

• Fixed user logout CSRF vulnerability
• Fixed handling of UID1's super user behavior in various tests
• Fixed access logic for Navigation blocks page
• Fixed RouteProvider::getRouteCollectionForRequest() poisoning query string of next request

Other Fixes

• Fixed Bootstrap not setting UTF-8 character encoding
• Fixed handling of deleted translated articles in search indexing
• Fixed handling of invalid values for core_version_requirement in update module
• Fixed FTPExtension class connection issues
• Fixed handling of entity type info updates during update.php execution
• Fixed various test failures and compatibility issues with PHPUnit 10

New Features

New Experimental Navigation Module

Drupal 10.3.0 introduces a new experimental Navigation module that provides a modern, accessible navigation system. This module offers:

• A drawer-based navigation experience that works well on both mobile and desktop
• Improved accessibility for keyboard users and screen readers
• Customizable navigation blocks with Layout Builder integration
• Icon support for menu items, with automatic fallback to using the first two letters of menu item text
• Announcement link functionality

Recipes API (Experimental)

A new experimental Recipes API has been added to core, allowing for easier site setup and configuration:

• Provides a standardized way to package and distribute site configurations
• Enables composable site building through recipe components
• Includes a command-line interface for applying recipes
• Supports default content as part of recipes

Workspace Improvements

Several enhancements to the Workspace module make content management more robust:

• New API for allowing modules to mark their forms as workspace-safe
• Ability to mark (VBO) actions as workspace-safe
• Improved workspace switcher redirection
• Pagination added to the workspace manage page
• Better handling of entity forms when editing in a workspace

New Hook for Entity Form Mode Alterations

A new hook_ENTITY_TYPE_form_mode_alter() has been added, allowing for more granular form alterations based on entity type and form mode.

PHP Attributes for Plugin Discovery

Plugin discovery has been converted from using annotations to PHP attributes for:

• Field Type plugins
• Layout plugins
• CKEditor 5 plugins

Security Updates

User Logout CSRF Protection

A significant security enhancement in Drupal 10.3.0 addresses a long-standing vulnerability (Issue #144538) by implementing CSRF protection for user logout functionality. This prevents cross-site request forgery attacks that could force users to log out unexpectedly.

Super User Access Policy Improvements

Multiple fixes have been implemented to address issues with UID1's super user behavior, improving the security model around administrative access:

• Fixed tests that relied on UID1's super user behavior across multiple modules
• Improved handling of super user access policy during installation
• Enhanced access control handling for various administrative functions

Input Validation Enhancements

• Added validation constraints to system.advisories
• Improved handling of invalid compressed ajax_page_state
• Better error handling for malformed input in various components

Error Handling Improvements

• More graceful handling of invalid data in various contexts
• Improved error messages for better security diagnostics
• Enhanced validation for uploaded files

Performance Improvements

Asset Handling Optimizations

• Improved AssetResolver caching to prevent repeatedly calculating the same set of assets
• Optimized AssetResolver to reduce processing time
• Enhanced handling of libraries with aggregate URLs
• Reduced unnecessary theme registry flushes when uploading files to media library

Caching Improvements

• Added static caching to LayoutTempstoreRepository for better performance
• Optimized twig_render_template with micro-optimizations
• Improved handling of cache data in EarlyRenderingControllerWrapperSubscriber

Test Performance Enhancements

• Optimized test ordering when run-tests.sh is used with a mixture of test types
• Reduced time of Migrate Upgrade tests by not outputting logs by default
• Improved test performance when --directory is used

UI Performance Improvements

• Replaced jQuery-based sticky table headers with pure CSS implementation
• Removed unnecessary JavaScript from Views configuration form
• Improved handling of layout shifts in various UI components
• Optimized mobile navigation to properly reset Drupal.displace() on closing

Impact Summary

Drupal 10.3.0 represents a significant step forward in Drupal's evolution, introducing new experimental features while improving existing functionality and fixing numerous bugs. The release focuses on enhancing user experience, developer tools, and performance.

The new experimental Navigation module is perhaps the most visible change, offering a modern, accessible navigation system that works well across devices. This addresses long-standing needs for better mobile navigation and accessibility in Drupal sites. Similarly, the experimental Recipes API lays groundwork for easier site setup and configuration, potentially transforming how Drupal sites are built and deployed.

For developers, the shift toward PHP attributes from annotations represents an important modernization of Drupal's code architecture. Combined with improved workspace APIs and file upload handling, these changes make development more consistent and maintainable.

Security improvements, particularly the CSRF protection for user logout, address important vulnerabilities. Performance optimizations in asset handling and caching should result in faster page loads and better resource utilization.

The focus on accessibility and UI improvements demonstrates Drupal's continued commitment to inclusive design, with fixes for layout shifts, keyboard navigation, and screen reader support making sites more usable for everyone.

While the experimental features will need time to mature before being widely adopted in production, the bug fixes and performance improvements make this release valuable for most Drupal sites. The deprecation of certain modules and functionality also helps prepare the way for future Drupal versions, giving developers time to adapt their code.