drupal 8.4.0

Drush users: Update to Drush 8.1.12+ or higher

Versions of Drush earlier than 8.1.12 will not work with Drupal 8.4.x. Update Drush to 8.1.12 or higher before using it to update to Drupal core 8.4.x or you will encounter fatal errors that prevent updates from running.

• If Drush is installed globally (i.e., generally available on the web host), Drush 8.1.12 and higher will successfully update Drupal 8.3.x to 8.4.0, but users may still see other error messages after updates have run.)
• If the site is built with Composer and includes Drush as a local dependency (less common), you should update your composer.json file to require at least Drush 8.1.15. Drush 8.1.14 will not work in the same composer project as Drupal 8.4.

Updated browser requirements: Internet Explorer 9 and 10 no longer supported

In April 2017, Microsoft discontinued all support for Internet Explorer 9 and 10. Therefore, Drupal 8.4 has as well. Drupal 8.4 still mostly works in these browser versions, but bugs that affect them only will no longer be fixed, and existing workarounds for them will be removed beginning in Drupal 8.5.

Additionally, Drupal 8's browser requirements documentation page currently lists incorrect information regarding very outdated browser versions such as Safari 5 and Firefox 5. Clarifications to the browser policy and documentation are underway.

Known Issues

Drupal 8.4.0 includes major version updates for two dependencies: Symfony 3.2 and jQuery 3. Both updates may introduce backwards compatibility issues for some sites or modules, so test carefully. For more information, see the "Third-party library updates" section below. Known issues related to the Symfony update include:

• Drush issues:
  • Incompatibility with Drush 8.1.11 and earlier.
  • Other error messages with Drush 8.1.12 and higher.
  • Incompatibility with Drush 8.1.14 and earlier for Composer-built sites.
• Certain file uploads may fail silently due to a Symfony 3 backwards compatibility break if they used the $deep parameter (which was already deprecated in Symfony 2.8 and is removed in Symfony 3.0. Check any custom file upload code that may have used the deprecated parameter and update it according to the API change record.

See the '8.4.0 update' tag for a list of known issues across projects.

Search the issue queue for known issues.

Important fixes since 8.3.x

Translators should take note of several string additions and changes since the last release.

File usage tracking

Drupal 8 has several longstanding file usage tracking bugs. To prevent further data loss, Drupal 8.4 has disabled the automatic deletion of files with no known remaining usages. This will result of the accumulation of unused files on sites, but ensures that files erroneously reporting 0 usages are not deleted while in use. Additionally, an issue with validation errors when saving content referencing these files has also been resolved.

The change record explains how sites can opt back into marking files temporary. If you choose to enable the setting, you can also set "Delete temporary files after" to "Never" on /admin/config/media/file-system to avoid permanent deletion of the affected files.

While the files will no longer be deleted by default, file usage is still not tracked correctly in several scenarios, regardless of the setting. Discussion on how to evolve the file usage tracking system is underway.

Configuration export sorting

• #2361539: Config export key order is not predictable for sequences, add orderby property to config schema resolves an issue where sequences in configuration were not sorted unless the code responsible for saving configuration explicitly performed a sort. This resulted in unpredictable changes in configuration ordering and confusing diffs even when nothing had changed. To resolve this issue, we've added an orderby key to the config schema that allows it to be sorted either by key or by value. Adding a preferred sort is strongly recommended.
• Two related issues remain open:
  • #2860531: Add orderby key to third-party settings relates to unsorted sequences which result in unexpected discrepancies in configuration during a configuration import.
  • #2885368: Config export key order for sequences: "orderedby" does not support cases where the order actually matters relates to various sequences in core and contributed modules in which the source order is important.

Revision data integrity fixes

• Previously, data from draft revisions for path aliases, menus, and books could leak into the live site. Drupal 8.4.0 hotfixes all three issues by preventing changes to this data from being saved on any revision that is not the default revision. These fixes improve revision support for both stable features and the experimental Content Moderation module.
• Correspondingly, Content Moderation now avoids such scenarios with non-default revisions by setting the 'default revision' flag earlier.
• Previously, saving a revision of an entity translation could cause draft revisions to go "missing". Drupal 8.4.0 prevents this by preventing the moderation state from being set to anything that would make the revision go "missing". Going forward, the entity system will also provide the 'revision_translation_affected' base field by default for all revisionable and translatable entity types for tracking such revisions.
• A similar but unrelated bug in Content Moderation has also been fixed in this release.

Other critical improvements

• When nodes were deleted, Menu UI module deleted their menu items. However, menu items may exist even whenm Menu UI module is not enabled and can also be attached to entities other than nodes. Therefore, menu item cleanup on entity deletetion is now performed by the Custom Menu Links module instead, covering the previously missing cases. A related issue that broke module uninstallation for some modules providing menu items for certain entity forms has also been resolved.
• A race condition occured in the Batch API when using fastcgi. The Batch API now ensures that the current batch state is written completely to the database before starting the next batch.
• When uninstalling modules, empty fields were left behind to be purged. However, without the field definitions from the module, it was not possible to purge them any more. Empty field deletion is now performed immediately instead to avoid this scenario.

New stable modules

The following modules, previously considered experimental, are now stable and safe for use on production sites, with full backwards compatibility and upgrade paths from 8.4.0 to future releases:

Datetime Range

The Datetime Range module provides a field type that allows end dates to support contributed modules like Calendar. This stable release is backwards-compatible with the 8.3.x experimental version and shares a consistent API with other Datetime fields.

Future releases may improve Views support, usability, Datetime Range field validation, and REST support. For bugs or feature requests for this module, see the core Datetime issue queue.

Layout Discovery

The Layout Discovery module provides an API for modules or themes to register layouts as well as five common layouts. Providing this API in core enables core and contributed layout solutions to be compatible with each other. This stable release is backwards-compatible with the 8.3.x experimental version and introduces support for per-region attributes.

Media

The new core Media module provides an API for reusable media entities and references. It is based on the contributed Media Entity module.

Since there is a rich ecosystem of Drupal contributed modules built on Media Entity, the top priority for this release is to provide a stable core API and data model for a smoother transition for these modules. Developers and expert site builders can now add Media as a dependency. Work is underway to provide an update path for existing sites' Media Entity data and to port existing contributed modules to the improved core API. Both versions cannot be used at the same time, so we also prevent the 1.x version of the contributed Media Entity module from being enabled at the same time as the core Media module.

Note that the core Media module is currently marked hidden and will not appear on the 'Extend' (module administration) page. (Enabling a contributed module that depends on the core Media module will also enable Media automatically.) The module will be displayed to site builders normally once user experience issues with it are resolved. Similarly, the REST API and normalizations for Media is not final and support for decoupled applications will also be improved in a future release.

Inline Form Errors

The Inline Form Errors module provides a summary of any validation errors at the top of a form and places the individual error messages next to the form elements themselves. This helps users understand which entries need to be fixed, and how. Inline Form Errors was provided as an experimental module from Drupal 8.0.0 on, but it is now stable and polished enough for production use. See the core Inline Form Errors module issue queue for outstanding issues.

Workflows

The Workflows module provides an abstract system of states (like Draft, Archived, and Published) and transitions between them. Workflows can be used by modules that implement non-publishing workflows (such as for users or products) as well as content publishing workflows.

Drupal 8.4 introduces a final significant backwards compatibility and data model break for this module, moving responsibility for workflow states and transitions from the Workflow entity to the Workflow type plugin. Read Workflow type plugins are now responsible for state and transition schema for full details on the API and data model changes related to this fix. Now that this change is complete, the Workflows module became stable!

While the module can be installed as-is, it is not useful in itself without either Content Moderation and/or some other module that requires it.

Content authoring and site administration improvements

• The "Save and keep (un)published" dropbutton has been replaced with a "Published" checkbox and single "Save" button. The "Save and..." dropbutton was a new design in Drupal 8, but users found it confusing, so we have restored a design that is more similar to the user interface for Drupal 7 and earlier.
• Previously, deleting a field on a content type would also delete any views depending on the field. While the confirmation form did indicate that the view would be deleted, users did not expect the behavior and often missed the message, leading to data loss. Now, the view is disabled instead. In the future, we intend to notify users that configuration has been disabled (as in this fix) as well as give users clearer warnings for other highly destructive operations.
• The Drupal toolbar no longer flickers during page rendering, thus improving perceived front-end performance.
• Options in timezones selector are now grouped by regions and labeled by cities instead of timezone names, making it much easier for users to find and select the specific timezone they need.
• Both the "Comments" administration page at /admin/content/comment and the "Recent log messages" report provided by dblog are now configurable views. The "Comments" administration page also has some default filters added.
• Useful meta information about a node's status is typically displayed at the top of the node sidebar. Previously, this meta information was provided by the Seven theme, so it was not available in other administrative themes. This meta information is now provided by node.module itself so other administration themes can access it.
• Views now supports rendering computed fields.

REST and API-first improvements

• Authenticated REST API performance increased by 15% by utilizing the Dynamic Page Cache.
• POSTing entities can now happen at /node, /taxonomy/term and so on, instead of /entity/node, /entity/taxonomy_term. Instead of confusingly different URLs, they therefore now use the URLs you'd expect. Backwards compatibility is maintained.
• There is now a dedicated resource for resetting a user's password.
• Time fields now are normalized to RFC3339 timestamps by default, fixing time ambiguity. Existing sites continue to receive UNIX timestamps, but can opt in. See the change record for more information about backwards compatibility and on how to opt in.
• Path alias fields are now normalized as well. See the change record for information about how this impacts API-first modules and other features relying on serialized entities.
• When denormalization fails, a 422 response is now returned instead of a 400, per the HTTP specification.
• With CORS enabled to allow origins besides the site's own host, submitting forms was broken unless the site's own host was also explicitly allowed. This is now resolved.
• Fatal errors and exceptions now show a backtrace for all non-HTML requests as well as HTML requests, which makes for easier debugging and better bug reports.
• Massive expansion of test coverage.

Performance and scalability improvements

• Drupal 8 caches at various different levels for more effective caching. However, this resulted in exessively growing cache tables with tens or hundreds of thousands of entries, and gigabytes in size. A new limit of 5000 rows per cache bin was introduced to limit this growth.
• The internal page cache now has a dedicated cache bin distinct from the rest of the render cache for improved scalability.
• The service collector pattern instantiates all services it collects, which is expensive, and unnecessary for some use cases. For those use cases, a new service ID collector pattern has been added and the theme negotiator updated to use it. See the change record for information about how to use the service ID collector for improved performance.
• The maximum time in-progress forms are cached is now customizable rather than being limited to a default cache lifetime of 6 hours. Sites can decrease the lifetime to reduce cache footprint, or increase it if needed for a particular site's usecase. See the change record to learn how to access this new setting.
• If there are no status messages, the corresponding rendering is now skipped. On simple sites that use the Dynamic Page Cache (the default), this can result in a 10% improvement when there are no messages!
• Optimized the early Drupal installer to check whether any themes are installed first before invoking an unnecessary function, which improves Drupal install time measurably for both sites and automated tests.

Developer experience improvements

• Adopted Airbnb JavaScript style guide 14.1 as the new baseline set of coding standards for Drupal core and contributed modules. See the change record for information about how to configure your project for eslint.
• Field type definitions can now enforce the cardinality of the field. See the change record for information about how to specify a cardinality via the annotation.
• Added new methods to make getting typed configuration entity representations easier. See the change record for more information about how to invoke these methods.
• The html_tag render element now supports nested render arrays, enabling the creation of dynamic SVGs. See the change record for information about how you can use this in your theme.
• Added more helpful errors when CSS is not properly nested under an existing category in asset libraries.
• Also see the change records for the 8.4.x branch for other changes for developers.

Automated testing improvements

• PHPUnit has been updated from 4.8.28 to 4.8.35 in order to incorporate a forward-compatibility layer for PHPUnit 4.8, which will be useful during a future migration to PHPUnit 5 or PHPUnit 6.
• Many former WebTestBase tests were converted to BrowserTestBase. Track current progress.
• The default approach for testing deprecated code has changed to require use of the Drupal core deprecation policy (@trigger_error()) to mark code deprecated; otherwise a test error will be thrown. See the change record for information about how to update phpunit.xml and how to test deprecated code.
• BrowserTestBase is no longer dependent on traits from Simpletest. Backwards compatibility is preserved.
• Resolved random test failures due to ResourceTestBase's HTTP client timeout of 30 seconds.

Third-party library updates

• Drupal's Symfony dependency has been updated from Symfony 2.8 to Symfony 3.2. This major version update is necessary because Symfony 2.8 support will end around the release of Drupal 8.6.0 next year. See the change record for information about Symfony 3 backwards compatibility breaks that affected Drupal core. Drupal 8 also requires Symfony 3.2.8 because of a bug in Symfony 3.2.7.
• #2533498: Update jQuery to version 3. Now that jQuery 3.0 has been released, jQuery 2.x will only be receiving security updates, so Drupal 8.4.0 ships with this library update. jQuery 3 features numerous improvements, including better error reporting. See the jQuery Core 3.0 Upgrade Guide for information on jQuery 3 backwards compatibility breaks that might affect the JavaScript code in your modules, themes, and sites.
• Correspondingly, jQuery UI has been updated from 1.11.4 to 1.12.1.
• The zurb/joyride library (used by the Tour module) has been updated to a development version higher than 2.1.0.1 to resolve an upstream incompatibility with jQuery 3. We will update to Joyride 2.1.1 once it is available with the needed fix.
• Other minor- and patch-level dependency updates in this release:
  • zendframework/zend-diactoros has been updated from 1.3.10 to 1.4.1.
  • jQuery Once has been updated from 2.1.1 to 2.2.0.
  • CKEditor has been updated from 4.6.2 to 4.7.2.
  • asm89/stack-cors has been updated from 1.0 to 1.1.
  • The minimum phpsec/prophecy requirement is now 1.4.
  • composer/installers has been updated from 1.2.0 to 1.4.0.
  • wikimedia/composer-merge-plugin has been updated from 1.4.0 to 1.4.1.
  • guzzlehttp/guzzle has been updated from 6.2.3 to 6.3.0.
  • mikey179/vfsstream has been updated from 1.6.4 to 1.6.5.
  • phpunit/phpunit has been updated from 4.8.35 to 4.8.36.
  • masterminds/html5 has been updated from 2.2.2 to 2.3.0.
  • symfony-cmf/routing has been udpated from 1.4.0 to 1.4.1.

Experimental modules

Migrate (beta stability)

Migrate provides a general API for migrations. It will be considered completely stable once all issues tagged Migrate critical are resolved.

• This release includes numerous developer experience improvements for Migrate and Migrate Drupal, including deprecating outdated references to "CCK", simplifying field type mapping, renaming several plugins to better capture their and many other API and documentation improvements. (Backwards compatibility is provided in each case Migrate is in beta.)
• Added the ability to provide the source module to migrations to help site owners review what data is being migrating, especially for cases where the source and destination module are not the same (for example if a new Drupal 8 module replaces old functionality.

Migrate Drupal and Migrate Drupal UI (alpha stability)

Migrate Drupal module provides API support for Drupal-to-Drupal migrations, and Migrate Drupal UI offers a simple user interface to run migrations from older Drupal versions.

• This release adds date and node reference support for Drupal 6 to 8 migrations.
• Core provides migrations for most Drupal 6 data and can be used for migrating Drupal 6 sites to Drupal 8, and the Drupal 6 to 8 migration path is nearing beta stability. Some gaps remain, such as for some internationalization data. (Outstanding issues for the Drupal 6 to Drupal 8 migration.)
• The Drupal 7 to Drupal 8 migration is incomplete but is suitable for developers who would like to help improve the migration and can be used to test upgrades especially for simple Drupal 7 sites. Most high-priority migrations are available. (Outstanding issues for the Drupal 7 to Drupal 8 migration.)
• Drush support for Migrate is currently only available in the Drupal Upgrade contributed module. (See the pull request to add support to Drush.)
• Conflicting text field processing settings are now identified and logged to avoid security or data integrity issues with the migration of plain and formatted text fields.
• Automatic redirects are now added for translation node paths that are no longer valid after migration has merged translations into a single node.
• A data integrity bug that resulted in duplicate comment types and incorrect comment_entity_statistics for node and forum comment migrations has been resolved.
• A bug that stopped public files from being migrated from D6 to D8 if the user first selected Drupal 7 in the UI has also been resolved.

Content Moderation (beta stability)

Content Moderation allows workflows from the Workflows module to be applied to content. Notable improvements in this release:

• Workflow states are now selected from a select list, rather than under a drop-button, which represents a significant usability improvement.
• Now that workflows can be applied to any revisionable entity type, Content Moderation adds entity type checkboxes to the workflow form. This allows site administrators to configure which entity types should have the workflow at the same time as they configure the workflow itself, for a more intuitive user experience.
• Content Moderation now prevents the deletion of workflows that are currently in use to prevent fatal errors and data integrity problems.
• The confusing terminology of "forward revisions" has been replaced with that of "pending revisions". If your contributed module refers to revisions that are not yet published, it should use this new term.
• The 'Latest revision' views filter has been rewritten to avoid relying on a custom {revision_tracker}, and that table has been removed from the database schema.

As per the experimental module process, there were some backwards-incompatible changes since Drupal 8.3.x. Experimental modules do not offer a supported upgrade path, but an unofficial upgrade path is available.

Field Layout (alpha stability)

This module provides the ability for site builders to rearrange fields on content types, block types, etc. into new regions, for both the form and display, on the same forms provided by the normal field user interface. Field Layout has had several bugfixes since 8.3.0, but no significant changes. See the entity display layout roadmap for the next steps for this module, which needs to become stable by 8.5.0 to remain in Drupal core.

Settings Tray (beta stability)

The Settings Tray module allows configuring page elements such as blocks and menus from the frontend of your site. Settings Tray has improved significantly since Drupal 8.3.0, including numerous user interaction and accessibility fixes, better compatibility with stable core modules like Quick Edit and Contextual Links, added documentation, and a CSS reset for better themer experience.

The module reached beta stability following completion of moving the off-canvas dialog renderer into a core component, and renaming the machine name of the module to settings_tray, to match its user-facing name. We hope to make Settings Tray stable by 8.5.0. To track progress, see the "outside in" roadmap issue.

Place Blocks (alpha stability)

This feature allows the user to place a block on any page and see the region where it will be displayed, without having to navigate to a backend administration form. 8.4.0-alpha1 was the deadline for Place Blocks to stabilize, but the module's roadmap was not completed. Furthermore, the module is not intended as a standalone feature and should instead be a built-in part of the Block system. For these reasons, Place Blocks module has been marked hidden in this release (it can still be enabled with Drush). The Place Blocks module itself will be turned into an empty module in Drupal 8.5.x, since ideally the core Block system will offer the same functionality in 8.5.0 (though this depends on completion of a core patch for the feature.)