Drupal Release: 10.2.0

TL;DR

Drupal 10.2.0 introduces significant enhancements to the CMS with a focus on improved developer experience, accessibility, and performance. Key updates include PHP 8.2 as the recommended PHP version, new validation constraints for configuration forms, migration to PHP attributes from annotations, and several UI improvements including a revamped Media revision UI. Security and accessibility fixes strengthen the platform, while new components like the Announcements Feed block and SDC components for Umami enhance content management capabilities. This release represents an important step forward in Drupal's evolution with numerous bug fixes and performance optimizations.

Highlight of the Release

• PHP 8.2 is now the recommended PHP version
• Migration from Doctrine annotations to PHP attributes
• New #config_target Form API property for simpler validation constraints
• Media revision UI added for better content versioning
• New Announcements Feed block available in Standard and Umami profiles
• CKEditor 5 updated to version 40.2.0 with support for inline HTML comments
• Improved accessibility with better contrast for required field indicators
• New SDC components for Umami (common footer block and badge component)
• Better error handling with improved backtrace display for logged throwables
• Performance improvements with compressed AJAX page state

Migration Guide

PHP Version Requirements

• PHP 8.2 Recommended: Drupal 10.2.0 now recommends PHP 8.2. While earlier versions (PHP 8.1+) are still supported, it's recommended to upgrade to PHP 8.2 for optimal performance and security.

PHP Attributes Migration

• Doctrine Annotations to PHP Attributes: Core has migrated from Doctrine annotations to PHP attributes. If your custom code extends or interacts with annotated classes, you should:
  1. Review your code for any dependencies on Doctrine annotations
  2. Update your code to use PHP attributes instead
  3. Test thoroughly as behavior might differ slightly

Form API Changes

• #config_target Property: If you're developing modules with configuration forms:
  1. Consider adopting the new #config_target property for simpler validation
  2. Review existing ConfigFormBase implementations for compatibility
  3. Be aware that ConfigTarget is not fully serializable in some edge cases

Deprecated APIs

• CacheDecoratorInterface: This unused interface has been deprecated. If your code implements or depends on this interface, plan to update it.
• ContextProvidersPass: This has been deprecated in favor of using service_id_collector. Update your service definitions accordingly.

Testing Framework Changes

• EntityReferenceTestTrait Renamed: The trait has been renamed to help discoverability. If your tests use this trait, update your use statements.
• Test Class Constructor: The use of TestClass constructor has been removed. Update your test classes if they extend this class.

Other Changes

• path.temporary Configuration: The path.temporary setting in system.file configuration has been deprecated. Use the 'file_temp_path' service instead.
• Log Level Changes: Routine log events have been demoted from "notice" to "info". If you have log filtering based on these levels, adjust your configuration.
• Block Content Permission Changes: Review your block content permissions as changes have been made to how "administer block content" permission works with revisions.

Upgrade Recommendations

Upgrade Priority: Medium

Drupal 10.2.0 introduces important improvements and bug fixes that benefit most sites, but doesn't contain critical security fixes that would necessitate an immediate upgrade. The upgrade is recommended for sites that want to take advantage of the new features and performance improvements.

Before Upgrading

1. Test on a Staging Environment: Always test the upgrade on a staging or development environment before applying to production.

2. Check PHP Compatibility: Ensure your hosting environment supports PHP 8.1 or higher, with PHP 8.2 recommended.

3. Review Custom Code:

   • Check for any custom code that might be affected by the migration from Doctrine annotations to PHP attributes
   • Review custom modules that extend or override Block Content or Media functionality
   • Test any custom form implementations that might be affected by Form API changes

4. Update Contributed Modules: Ensure all contributed modules are updated to versions compatible with Drupal 10.2.0.

5. Backup Your Site: Create a complete backup of your site files and database before upgrading.

Upgrade Path

• From Drupal 10.1.x: Direct upgrade to 10.2.0 is supported and recommended.
• From Drupal 10.0.x: Upgrade to the latest 10.1.x release first, test thoroughly, then upgrade to 10.2.0.
• From Drupal 9.x: Upgrade to Drupal 10.0.x first, then follow the path above.
• From Drupal 8.x or earlier: Follow the standard major version upgrade path through Drupal 9 first.

Post-Upgrade Steps

1. Clear Caches: Clear all caches after the upgrade is complete.
2. Run Update Scripts: Run any pending database updates.
3. Test Critical Functionality: Thoroughly test all critical site functionality.
4. Review Logs: Check for any new warnings or errors in your logs.
5. Update Configuration: If you use the new features like the Announcements Feed block, configure them as needed.

Bug Fixes

Content Management

• Block Content: Fixed issue where adding or editing a block through the UI saved the entity twice.
• Entity Autocomplete: Fixed issue where entity autocomplete form element ignored entities with label "0".
• Default File Visibility: Fixed issue where default file visibility setting was not respected.
• Field Display: Fixed wrong comment display for sites configuring base field display in the UI.
• Default Value Widget: Fixed issue where default value widget was not updated on field config change.

Configuration Management

• Config Import: Fixed issues where config saved or deleted during import did not have correct initial values set.
• Custom Theme Uninstall: Fixed issue where uninstalled custom themes could get stuck in config blocking config import.

User Interface

• Dialog Focus: Fixed multiple issues with dialog focus management:
  • Dialogs now properly receive focus when opened
  • Focus is properly returned after AJAX updates
  • Focus is maintained when inside a dialog
• Layout Issues:
  • Fixed fieldset legend positioning regression
  • Fixed table filter layout shift (jank) on page load
  • Fixed table drag elements creating horizontal scroll on mobile
  • Fixed long string breaking Claro layout
  • Fixed misalignment between dropbuttons and regular buttons

Multilingual

• Language Switcher: Fixed regression where language switcher block returned links to node on the frontpage.
• Translation: Fixed JavaScript errors in entity-form.js when retranslate checkbox does not exist.
• Menu Links: Fixed invalid argument exception when changing language of node with menu link to und or zxx.

Performance

• Fiber Loops: Fixed issue where Fiber loops in Renderer and BigPipe were never suspended.
• Cache Issues: Fixed faulty permanent config cache on failed SQL server connection.
• RSS Feed: Fixed issue where RSS Feed header reverted to text/html when cached.

Security

• Password Handling: Fixed PHP 8 warning when user password is null if user has never logged in.
• Version Information: Removed core version from install.php when site is already installed to prevent information disclosure.

Other

• Forum Module: Fixed missing primary key in forum_index table.
• File Extensions: Fixed FileUploadHandler::handleExtensionValidation to provide fallback for sites still using file_validate_extensions.
• JSON:API: Fixed issue where BlockContent JSON:API collection endpoint didn't return unpublished blocks when filtered without proper permissions.
• Components: Fixed error thrown by components without props.
• Batch Processing: Fixed JavaScript error when exceptions occur in batch processing.

New Features

Developer Experience

• PHP Attributes Support: Replaced Doctrine annotations with PHP attributes for improved performance and modern PHP practices.
• #config_target Form API Property: New property makes it simpler to use validation constraints on configuration forms.
• Validation Constraints: Added validation constraints to taxonomy settings and numeric fields.
• CallableResolver Implementation: Improved handling of callbacks in Renderer and MenuLinkTree.

Content Management

• Media Revision UI: Added a complete revision UI for Media entities, allowing better content versioning and history tracking.
• Block Content Revisions: Improved permission handling for block content revisions with "administer block content" permission.
• Announcements Feed Block: New block to display Drupal project announcements, now available in both Standard and Umami profiles.

User Interface

• SDC Components for Umami: Added new Single Directory Components including:
  • Umami common footer block component
  • Badge component for recipes
• Deployment Identifier: Now displayed on the status page for better environment tracking.
• CKEditor 5 Enhancements:
  • Updated to version 40.2.0
  • Added support for inline HTML comments
  • Improved style warnings for unsupported elements

Testing and Development

• Database Query Assertions: New functionality to assert the number of database queries run during tests.
• Symfony Components: Added Symfony's Filesystem and Finder components to core.

Security Updates

Authentication and User Management

• Login Form Security: Added autocomplete attributes on login form and password reset form to improve security and user experience.
• Password Handling: Fixed PHP 8 warning when user password is null if user has never logged in, improving security of password management.

Information Disclosure Prevention

• Version Information: Removed Core version from install.php when the site is already installed to prevent information disclosure that could be used by attackers to target known vulnerabilities.
• JSON:API Access Control: Fixed issue where BlockContent JSON:API collection endpoint didn't return unpublished block content when filtered without administer block content permission, preventing potential information disclosure.
• Revision Log Fields: Fixed information disclosure access bypass for revision log fields when the JSON:API module is enabled.

File Handling

• File Extension Validation: Fixed FileUploadHandler::handleExtensionValidation to provide fallback for sites still using file_validate_extensions, ensuring proper security checks for uploaded files.

Configuration Security

• Validation Constraints: Added validation constraints to taxonomy settings and numeric fields, improving input validation and preventing potential security issues.
• Config Target Validation: New #config_target Form API property makes it simpler to use validation constraints on configuration forms, improving security through better validation.

Performance Improvements

AJAX and Frontend

• Compressed AJAX Page State: Implemented compression for ajax_page_state, reducing the size of AJAX requests and improving performance for sites with many libraries.
• JavaScript Optimizations:
  • Improved AJAX focus handling integration for better performance
  • Fixed race condition on AJAX change event and form submission
  • Enhanced machine name AJAX focus handling

Backend Optimizations

• PHP Attributes: Migration from Doctrine annotations to PHP attributes provides performance benefits through native PHP functionality.
• TypedData Improvements: Added comments explaining performance improvements in TypedData implementation.
• Log Level Adjustments: Demoted routine log events from "notice" to "info" level to reduce log noise and improve performance.

Cache Improvements

• Cache Handling: Fixed issues with cache tables during system updates.
• RSS Feed Caching: Fixed issue where RSS Feed header reverted to text/html when cached, ensuring proper content type headers are maintained.

Development Tools

• GitLab CI Optimizations:
  • Optimized resource requests in GitLab CI pipelines
  • Improved test-only job workflow
  • Better handling of child jobs to reduce load
  • Added performance tests job to GitLab and send data to OpenTelemetry

Library Updates

• JavaScript Dependencies: Updated various JavaScript dependencies to latest versions for better performance.
• CKEditor 5: Updated to version 40.2.0 with performance improvements.
• Symfony Components: Updated to Symfony 6.4 with performance enhancements.

Impact Summary

Drupal 10.2.0 represents a significant enhancement to the Drupal ecosystem with improvements spanning developer experience, user interface, accessibility, and performance. This release strikes a balance between introducing new features and refining existing functionality.

For developers, the migration from Doctrine annotations to PHP attributes marks an important modernization of Drupal's codebase, aligning with current PHP best practices and potentially improving performance. The new #config_target Form API property simplifies validation constraints implementation, making configuration forms more robust and easier to develop. These changes, along with the recommendation of PHP 8.2, demonstrate Drupal's commitment to staying current with PHP advancements.

Site builders benefit from several new components and UI improvements. The addition of the Announcements Feed block to both Standard and Umami profiles provides an easy way to keep site administrators informed about Drupal project news. New SDC components for Umami enhance the demonstration profile's capabilities and serve as examples for custom component development.

Content editors will appreciate the new Media revision UI, which brings the same versioning capabilities to media that have long been available for nodes. This feature, combined with improvements to block content revisions, strengthens Drupal's content management capabilities and provides better editorial workflows.

Accessibility improvements, including better contrast for required field indicators and enhanced dialog focus management, demonstrate Drupal's ongoing commitment to creating inclusive experiences. These changes benefit all users but are particularly important for those using assistive technologies.

Performance optimizations, such as compressed AJAX page state and various backend improvements, should result in a more responsive experience, especially for complex sites with many modules and libraries.

The numerous bug fixes address pain points across various subsystems, from configuration management to multilingual functionality, making the platform more stable and reliable. Security enhancements, while not addressing critical vulnerabilities, strengthen the platform's overall security posture.

Overall, Drupal 10.2.0 delivers meaningful improvements that enhance the platform's capabilities while maintaining stability, making it a recommended upgrade for most Drupal 10 sites.