Skip to content

Latest commit

 

History

History
135 lines (102 loc) · 5.33 KB

best-practices.md

File metadata and controls

135 lines (102 loc) · 5.33 KB
Raw

Best Practices

"How should I write code?"

This document is a work in progress. Unlinked items are planned topics, feel free to contribute.

##Exporting configuration

All site functionality should be represented in version-controlled code. This includes all configuration. Drupal configuration is typically exported via Features.

Features

Features should generally follow the [KIT Feature specifications] (https://www.drupal.org/project/kit).

Notable principles from this specification include:

  • A feature should provides a collection of Drupal entities which taken together satisfy a certain use case. Example:a gallery feature provides a gallery view, a photo content type, and several blocks allowing a user to add new photos and browse those submitted by others.
  • A feature must, to the best of the creator's knowledge, use a unique code namespace.

Additional guidelines include:

  • Each feature should be as discrete and independent as possible. Feature dependencies should be carefully considered! All dependencies should be one-way. Circular dependencies should never exist.

Exceptions:

  • Distribution compliance guidelines are only applicable for distributions
  • Sites will often need to contain a single "sitewide" feature that defines global configuration and is required by all other features. This can be viewed as a "core" feature but should not be abused as a dumping ground for miscellany.

Common mistakes:

  • Creation of large features that encompass many un-related components. E.g., multiple un-related content types, views, roles, permissions are all bundled into a single feature.
  • Poor design of dependencies, e.g., creation of circular dependencies.
  • Each feature has too many dependencies, so no one feature can be used in isolation, or a single feature becomes impossible to disable. E.g., the "Workflow" feature depends on the "Press Room" feature because it requires field_body which is provided by "Press Room."
  • Features are too granular. E.g., there is a separate feature for each role, a feature contains only a single view, etc.

##Configuration updates

  • If a change is happening, that change needs to be documented in code, preferably an update hook. E.g.,
    • Reverting features and feature components features_revert_module()
    • Enable / disable module module_enable()
    • Adding indexes to databases db_add_index()
  • Updates needs to be actively monitored. This should be done using NewRelic, SumoLogic, Logstreaming, and/or other monitoring tools.
  • Updates need to be intentional. E.g., don't use cloud hooks or cron jobs to automatically execute updates or clear caches.

##Caching

Without caching, Drupal is slow. As a general rule of thumb, try to cache everything that you can and try to invalidate that cache only when it is likely to be stale.

Caching is complex. Because caching is so complex, it's difficult to provide general guidelines for caching strategies. Here are the factors the should be considered when making caching decisions:

  • What is serving the cache? E.g., CDN, Varnish, Memcache, DB, APC, etc.
  • What is being cached? An entire page, one component of a page, bytecode, etc.
  • Is the cache context-aware? I.e., is there only one version of the cached data or might it differ depending circumstances? E.g., the "Welcome [username]" block changes depending on the logged-in user.
  • What circumstances render the cached data stale? E.g., a cached view of press releases is stale when a press release is updated.
  • How should the cache be invalidated? E.g., invalid after X minutes, triggered by a user action, etc.

Specifically, ensure that you are properly caching data at every level possible, including:

  • Page caching (Varnish)
  • Database query caching (Memcache)
  • Views caching
  • Block caching
  • Panels caching
  • Entity caching
  • Twig caching
  • APC / Opcache (Code caching)
  • Static caching
  • CDN (Content Delivery Network)

See the Drupal 8 Cache API documentation for information in implementing your caching strategy.

##Patching

All modifications to contributed code should be performed via a patch. For detailed information on how to patch projects, please see [../patches/README.md] (../patches/README.md)

##Views

Please see views.md.

##Logging

  • Any configuration changes from custom modules should be logged to watchdog
  • User activity should generally be logged (see Acquia Library recommendations)
  • Any destructive actions must be logged

##Building content types

@todo Document:

  • Appropriate time to use fields
  • Audit for overly complex content types
    • Reason: All fields loaded for each node load
    • Use case: Needs translations, user-facing form, revisions, etc.