Last updated 23 February 2017.

Core changes must pass through a series of "gates" to ensure their quality is up to standards. Gates are essentially "checklists" that can be used to evaluate a patch's readiness, by both developers and patch reviewers/core committers.

The purpose of gates is two-fold:

  • Focus on only the most important items in each category (try to limit to 5 or fewer), so that the process is neither too complex nor too overwhelming for developers to follow.
  • Do not create additional burden on the respective individual teams. Rather, have well-documented resources so that developers have what they need to write gate-satisfying code, and reviewers can easily check for gate satisfaction.

The following gates (identified during Dries Buytaert's keynote during DrupalCon Chicago) will be used for assessing Drupal core patch readiness.

Looks scary, right? Please note the "When is this needed?" column. Not all patches need to pass all of these gates, but they are all documented here in one place so there are no surprises.



Description When is this needed? Details Resources
Issue summary is created Required for any issue that cannot be understood easily at first glance. Recommended for all issues. Edit the original issue node to summarize the issue, using the template. Summary template
In-code API documentation is added or updated Required for all patches that change or add to code behavior. All functions, classes, files, constants, etc. that are added or updated must be documented. (minimum requirements) API documentation standards, Minimum requirements for in-code documentation
module.api.php doc is added or updated Required for all patches invoking new hooks or changing how hooks are invoked. All new and updated hooks invoked by the code (including drupal_alter() calls) must be documented. Hook documentation standards
hook_help() doc and module description are added/updated Required for all patches that add modules or change the user interface. Help text standards
Change record Required if the patch makes API or user interface changes (both BC breaks and new additions) that module or theme developers need to know about, or that will need to be documented outside of the patch. Before commit, API change and User interface change sections from the issue summary are added as a change record. (Change nodes will track additional developer/themer documentation that needs to be updated, in turn.) Use tag “Needs change record” to indicate the change node(s) have not yet been created.


Discussion: Defining the Drupal 8 performance gate

Description When is this needed? Details Resources
SQL queries If there is a new or changed SQL query in a patch Changes that add or modify SQL queries should include: EXPLAIN output, description of indexes added or changed, indication of how often the query is likely to run and under what circumstances. The goal is not to add additional database calls unless absolutely necessary, and to ensure that all queries scale when using large data sets (avoiding scanning large numbers of rows, filesorts, temporary tables etc.) Devel module, MySQL EXPLAIN documentation
Caches Add a cache only when slowness has been demonstrated. If a contrib module or core module could be slow in some cases, add caching strictly for the part that is slow. Caches degrade developer and admin experience. It gets very hard to clear them during all the right moments, given how flexible Drupal is. Cache invalidation is a huge, complex topic in computer science. We are best off avoiding caches when possible. Static caches are only slightly less evil than persistent caches.
Memory usage If a patch changes or adds any resource that is statically cached or in a global, or involves changes to cache/registry rebuilds Ideally post before/after xhprof detail for the area of code being modified. Devel memory usage information may be sufficient xhprof, devel, xdebug trace files
CPU If a patch adds or changes any code that is run during a 'normal' request to Drupal, especially up to and including full bootstrap, or during the page rendering process Ideally post before/after xhprof or cachegrind detail for the area of code being modified. In some cases benchmarks via ab or another load testing tool may be sufficient. xdebug, devel
System calls If a patch adds or modifies include/require, file_exists()/file_mtime(), time() calls during normal operation or cache rebuilds Post before/after xhprof, cachegrind or strace detail for the area of code being modified. Strace, xhprof, xdebug
Front end If a patch makes significant changes to JavaScript or CSS If refactoring commonly used JavaScript, post profiling data (not sure on tools). If changing JavaScript and/or CSS aggregation logic, size and number of aggregates across several page requests should be posted to the issue google chrome toolbar, firebug


Discussion: Defining the Drupal 8 accessibility gate

Description When is this needed? Details Resources
Conforms to WCAG 2.0 and ATAG 2.0 When changing the UI. Common accessibility issues and tests are listed below. The goal for Drupal core is Level AA conformance with WCAG and ATAG 2.0. Use existing UI patterns to minimize the opportunity for accessibility or usability problems. Tag issues that introduce new patterns with "needs accessibility review". WCAG 2.0, ATAG 2.0, Drupal Accessibility Statement, and More about Drupal core conformance and UI patterns
HTML structure meets WCAG 2.0 When introducing new HTML structure or semantics, such as when changing templates or theme functions. Run an automated checking tool like the WAVE Toolbar. Test before and after a patch to verify that the patch does not introduce new errors. WAVE Toolbar and More about Automated Checking
Text color has sufficient contrast When introducing new foreground and background combinations, such as when changing CSS. Run a contrast test such as Contrast-A to check and repair color combinations. Visual presentations should meet WCAG Level AA contrast conformance. Contrast-A and More about Contrast.
Form fields are labeled When adding forms or changing fields, such as when using Form API. Every form field needs a correctly associated label. Run a test using the WAVE Toolbar (see above) on any new or changed forms and fix any incorrect labels. More about #title and #title_display
Javascript is keyboard-usable When developing new Javascript UI interactions or AJAX widgets. Test using only your keyboard (unplug your mouse). Verify that the UI can be fully operated using only a keyboard. More about Javascript accessibility


Description When is this needed? Details Resources
Tag issues with 'usability' Any patch that changes the user interface. UX team members follow this tag, this helps them find the right issues to review. Use 'needs usability review' for when a design decision is needed to move things forward. usability issues
User interface guidelines are followed, and new patterns are documented. Any patch that changes the user interface. By following the user interface standards we create a more consistent experience. Provide a rationale when you deviate; and document new interface patterns. UI standards
Make it easy for people to give design feedback. Any patch that changes the user interface. Supply screenshots and rationale on how your change affects the user.



Description When is this needed? Details Resources
Check test coverage and ensure all tests pass When changing/refactoring existing code
  • Ensure the code being worked on has test coverage.
  • No patch can be marked RTBC if there are outstanding test failures, since core has a 100% pass rate policy.
  • If the issue might affect specific environments differently (such as a change affecting how database queries are built), the test-only patch should be tested against all supported environments in the automated testing infrastructure.
Drupal core automated testing results
Add new tests When adding new features
  • New features should be accompanied by automated tests.
  • If the feature does not have an implementation, provide a test implementation.
  • WebTestBase has been deprecated as of February 21, 2017. Use the PHPUnit BrowserTestBase API for new tests.
  • Some web tests are not converted from the old SimpleTest WebTestBase. If an existing, unconverted class using SimpleTest already tests the functionality, use that instead of adding a duplicate test. These remaining SimpleTests will be updated to the new API eventually.
  • Otherwise use UnitTestCase, KernelTestBase, BrowserTestBase or JavascriptTestBase as appropriate.
Testing documentation
Upload a test case that fails When fixing bugs in PHP code Bug fixes should be accompanied by changes to a test (either modifying an existing test case or adding a new one) that demonstrate the bug. This can be shown by uploading a patch with only the test changes, which's automated testing system should show as a fail, alongside a patch containing both the tests and the bug fix itself. If a bug fix is not accompanied by tests, there should be an explanation in the issue for why no tests are needed (usually only for trivial bugs where testing would be convoluted) before it is marked RTBC. Patches that need tests written can have the Needs tests tag added. If the issue might affect specific environments differently (such as a change affecting how database queries are built), the test-only patch should be tested against all supported environments in the automated testing infrastructure.

See the previous row for documentation about test types.
Testing documentation
Issues needing tests
Add Javascript test When making JS changes Add a PHPUnit JavaScript test must be included with the patch (preferred) or a followup filed to add a JavaScript test. PHPUnit JavaScript test
Manually test in browsers and provide screenshots or screencasts When making markup or CSS changes Drupal core does not have automated visual regression testing. Changes to CSS or markup should normally be accompanied by confirmation that this has been tested in the browsers Drupal core currently supports. For large changes or bug fixes, screenshots or screencasts are ideal for demonstrating the impact of the changes. ...
Provide an example module When a new feature is not implemented by Drupal core When adding major new features that are not implemented by core (i.e. API-only features), example code should be provided that demonstrates the feature (typically in a test module in core).

Appendix: Additional information linked from above tables

Minimum requirements for in-code documentation

When a patch changes code behavior, all code that is added or updated must have:

  1. Documentation blocks for all files, interfaces, classes, methods, class members, functions, hooks, and constants, which must contain:
    • A one-line summary (80 characters or fewer).
    • Typed @param, @return, @var, and @throws (with descriptions on param/return) where required by the API documentation standards.
    • Longer explanations for anything complicated.
  2. Inline comments to explain the code flow.

The documentation must be clear and complete. Typos, verb tenses, formatting, and the like may be cleaned up in follow-up issues for large patches where it would hold up progress, at the committer's discretion.

More about Drupal core conformance and UI patterns

The accessibility goal for Drupal core is WCAG 2.0 and ATAG 2.0 Level AA. We want to reduce barriers to ensure that sites are Perceivable, Operable and Understandable, and Robust (POUR), and provide for the use of a variety of assistive technologies. It is important to think about accessibility when developing new user interfaces and to become familiar with successful and conforming implementations.

UI Patterns. Following existing user interface patterns already used in Drupal core will reduce the opportunity for accessibility or usability problems. New user interface patterns will likely require review by the accessibility and usability teams.

Problem Patterns. There are known patterns in core that are highly likely to cause accessibility problems, for example modal dialogs or interactive jQuery calls. If your patch includes one of these known patterns please check with accessibility team by tagging the issue with "needs accessibility review".

Testing is very important when introducing or redeveloping a UI pattern. If you are still unsure after running through the basic testing procedures, please check with accessibility team by tagging the issue with "needs accessibility review". The earlier a new or changed pattern is checked for accessibility the easier it can be corrected.

More about Automated Checking

Automated checkers do not guarantee accessibility and do not check all WCAG 2.0 criteria. Some criteria require human review and problems may be raised in the issue queue.

The WAVE Toolbar is a recommended checker. Other popular checkers include: the WAVE web app, FAE and the Firefox Accessibility Evaluation Toolbar.

Running the automated check before and after applying a proposed patch is important. Some parts of Drupal core cause errors or warnings in WAVE and other tools. New patches should not introduce additional errors.

More about Contrast

See for background information and other color contrast tools.

More about #title and #title_display

In the Drupal Form API, the new #title_display property allows you to choose the proper location for a form label to be displayed. It prints the label in the chosen location or makes it invisible off-screen while still preserving its accessibility.

See the Form API documentation for #title_display.

It is not accessible to remove the label by emptying the #title property: unset($element['#title']) ... or by using CSS display: none. Both of those techniques were used in Drupal 6 and earlier when there was no built-in support for locating form labels off-screen or as tool-tips.

More about Javascript Accessibility

Keyboard accessibility is a major concern when creating Javascript-based widgets, UI interactions, and AJAX functionality. "Keyboard only" is when you only use the keyboard to interact with the user interface. Many disabled users cannot use a mouse or other pointing device. Try using each feature of a new interface without using a mouse or trackpad. Problems with keyboard only operations will quickly identify areas to focus on.

Another kind of Javascript accessibility problem is the visibility of content that is dynamically loaded or updated by AJAX calls. Using existing UI patterns is encouraged to avoid accessibility problems. New user interfaces of this type will likely require design and collaboration with the accessibility and usability teams. Contributors are encouraged to seek design assistance as early in the design cycle as possible by tagging any issue with "needs accessibility review".

Drupal core includes numerous examples of UI patterns that have been made accessible with Javascript and/or ARIA markup. These include: drag-n-drop tables, vertical tabs, the password strength checker, and auto-complete fields.