params.json

{"name":"UN World Food Programme: Drupal 7 Standards & Best Practice","tagline":"The United Nations World Food Programme guide to developing Drupal 7 projects.","body":"Author : Andrew Holgate\r\n\r\nDate : December 10, 2014\r\n\r\nVersion : v0.9.0\r\n\r\n# About this Document\r\n\r\nThe purpose of this guideline is to ensure that all Drupal 7 projects follow the same best practices.\r\n\r\nThis document contains a list of modern, sensible Drupal and development practises that must be followed in order to be UN WFP compliant. Each topic is covered briefly with relevant resource links for additional clarification and examples.\r\n\r\n# Project Expectations\r\n\r\n## Definition of \"Done\"\r\n\r\nA ticket or task is only considered \"done\" when the changes\r\n\r\n1. Adhere to this guidelines.\r\n1. Successfully pass all tests\r\n1. Deployable through an automated process into a production-identical environment.\r\n\r\n## Realistic Task Completion Estimates\r\n\r\nAll timings for task completion must include all of the guidelines outlined in this document. Non-compliant code can only be committed to the repository when it is specifically requested before the task begins, it is clearly defined what part of the guideline will not be followed and a compliance completion roadmap is agreed upon.\r\n\r\nIt is the responsibility of each developer in the project team to understand and be able to implement the best practices outlined in this document.\r\n\r\nThe project must function correctly under all of the following circumstances:\r\n\r\n* Using proxy forwarding, therefore HTTP calls must use [drupal_http_request()](https://api.drupal.org/api/drupal/includes%21common.inc/function/drupal_http_request)\r\n* Using PHP accelerators, such as [APC](http://pecl.php.net/package/APC) and [Zend OPcache](http://pecl.php.net/package/ZendOpcache)\r\n* Using in-memory caching, such as [MemCache](http://memcached.org/) and [Redis](http://redis.io/).\r\n* Using an SMTP mail server.\r\n* Using both http and https protocols, therefore no-hard coding of internal paths.\r\n* Multilingual project, therefore [t()](https://api.drupal.org/api/drupal/includes%21bootstrap.inc/function/t) must be used for all user visible text, passing dynamic variables through as a parameter.\r\n* Desktop, tablet and mobile devices, therefore a mobile or responsive theme is required.\r\n* WFP standard browsers: Internet Explorer 8, Firefox and all modern browsers.\r\n\r\n# Development Workflow\r\n\r\n## Quality Assurance\r\n\r\nAll code pushed into any branch of a repository must strictly follow the best practice outlined in this document. Each commit will be carefully reviewed and evaluated by internal QA and any code found to be non-compliant will be rejected.\r\n\r\n## Acceptance Testing\r\n\r\nInitial Acceptance Testing is performed on successfully deployed changes on the staging server, using a current clone of the production system (database, codebase, files directory, etc).\r\n\r\n## Automated Deployment\r\n\r\nWe take an \"Automate everything approach\": All deployments of project changes must be automated and function without any manual intervention, such as changes via the admin UI.\r\n\r\nThe deployment script is:\r\n\r\n```\r\n# Pull all code changes from the repo and update dependencies.\r\ngit pull origin master && composer update --no-dev\r\n# Run all database updates and revert all project Features.\r\ndrush updatedb -y && drush features-revert-all -y\r\n# Clear all Drupal caches.\r\ndrush cache-clear all\r\n```\r\n\r\nTo achieve automated deployment, the [hook_update_N()](https://api.drupal.org/api/drupal/modules%21system%21system.api.php/function/hook_update_N) hook should be used extensively, including the installation and deinstallation of modules as well as removal of fields and variables, etc.\r\n\r\nOnce successfully deployed, all project Features should be in the default state.\r\n\r\n## Code Review and Testing\r\n\r\nThe following tests must pass before being committed to the repository.\r\n\r\n* [PHP_CodeSniffer](http://pear.php.net/PHP_CodeSniffer) to ensure the PHP, JS and CSS code follows standards.\r\n    * [Coder Sniffer](https://www.drupal.org/project/coder) to test for Drupal standards.\r\n    * [Drupal 7 Security Audit](https://github.com/Pheromone/phpcs-security-audit).\r\n    * [DrupalPractice sniffer](https://www.drupal.org/project/drupalpractice).\r\n    * [DrupalStrict](https://github.com/andrewholgate/drupalstrict), including cyclomatic complexity and nesting maximums.\r\n* [PHP Mess Detector](http://phpmd.org/) to identify potential PHP problems.\r\n* [PHP_Depend](http://pdepend.org/) to identify parts of the project where a code refactoring should be applied.\r\n* [PHP Copy/Paste Detector](http://github.com/sebastianbergmann/phpcpd) to identify duplicated code.\r\n\r\nAll code review tests can be run from the project root by executing:\r\n\r\n```\r\n./scripts/review.sh\r\n```\r\n\r\nWe use [PHPUnit](https://phpunit.de/) for unit testing. Important custom functionality of projects must always include Unit Tests.\r\n\r\n## Pre-commit Checklist\r\n\r\n1. Have you exported all database changes to the relevant Features, including all variables, configurations, permissions, cache settings, tags and descriptions?\r\n1. Are the versions and dependencies correct for the Features?\r\n1. Does the code and architecture adhere to the guidelines?\r\n1. Is all user-visible text being translated using the t() function?\r\n1. Are there enough code comments and are they  sufficiently clear and verbose?\r\n1. Have you run Coder and other PHP tools for testing to check against the Drupal Coding Standards for spacing, basic security, etc?\r\n1. Has it been done in such as manner as to allow for automatic deployment?\r\n1. Have you manually reviewed the code diff to ensure that nothing missing or extra being committed?\r\n1. Has it been peer reviewed?\r\n\r\nIf all developers follow the best practice, the entire project code base will look as if it's been written by one developer, such as seen in [Drupal core](http://cgit.drupalcode.org/drupal/tree/modules/node/node.module?h=7.x#n681).\r\n\r\n# Environments\r\n\r\n## Minimum Required Setup\r\n\r\n* A development server for current development.\r\n    * All [error reporting must be shown](https://www.drupal.org/node/1056468) and logged.\r\n    * Logging of all [MySQL slow queries](http://dev.mysql.com/doc/refman/5.5/en/slow-query-log.html) over 1 second.\r\n* A staging server for performing deployments.\r\n    * All error reporting, caching and aggregation must be turned on.\r\n    * Logging of all MySQL slow queries over 1 second.\r\n\r\nBoth servers must be accessible via an [htdigest login and password](http://httpd.apache.org/docs/2.4/programs/htdigest.html) and use the [Environment Indicator](https://www.drupal.org/project/environment_indicator) module for environment and commit identification. The HTTP server and MySQL slow query log files should also be accessible via a URL.\r\n\r\nAll environment specific configurations must be stored in the non-revisioned [settings.local.php](https://api.drupal.org/api/drupal/sites!example.settings.local.php/8) file. Configurations such as database credentials, caching settings, site_mail variable,  smtp server variables, etc. Sensitive data must never be stored inside of the code repository.\r\n\r\nDuring development, content must be included in order to fully evaluated the process. In the case of real data being unavailable, test data should be generated using the [Devel](https://www.drupal.org/project/devel) module.\r\n\r\nUnless otherwise specified, current recommended, stable versions must be used, such as for contributed modules, [PHP](https://www.drupal.org/requirements), [drush](https://github.com/drush-ops/drush#drush-versions), etc.\r\n\r\n# Drupal Project Structure\r\n\r\nThe WFP Drupal project template must be used for all Drupal projects. The project template is based on the [Lullabot Drupal Boilerplate](https://github.com/Lullabot/drupal-boilerplate). WFP projects use Composer for project dependency management, including contributed module and themes as well as 3rd party library dependencies.\r\n\r\n## Project Directory Structure\r\n\r\n```\r\nproject_name/\r\nrelease/\r\n  v0.9.5/\r\n  ..\r\n  v1.0.0/\r\n    .git/\r\n    build/\r\n    code/\r\n    composer.json\r\n    error.log -> project_name/logs/error.log\r\n    slow_queries.log -> project_name/logs/slow_queries.log\r\n    ..\r\ncurrent -> release/v1.0.0/build\r\nlogs/\r\n  error.log -> /var/logs/apache/project_name.errors.log\r\n  slow_queries.log -> /etc/mysql/slow_queries.log\r\nsettings.local.php\r\n```\r\n\r\n# Drupal Project Architecture\r\n\r\n## Required Drupal Contributed Modules\r\n\r\n* Features\r\n* Strongarm\r\n* Universally Unique ID\r\n* UUID Features\r\n* Entity API\r\n* Diff\r\n* Chaos Tools\r\n* Google Analytics\r\n* Advanced CSS/JS Aggregation\r\n\r\n## Use Declarative Architectural Design\r\n\r\nBefore development begins, the architecture must be declared and agreed upon using the [Drupal Configuration Spreadsheet Standard](https://github.com/sreynen/Drupal-Configuration-Spreadsheet-Standard).\r\n\r\n## Contributed Module Selection\r\n\r\nOnly install the essential contributed modules to achieve the functionality required. Modules which are not used on the project must be uninstalled immediately.\r\n\r\nFor Drupal 7 [Future-proof your Drupal 7 site](https://www.drupal.org/node/2287495) contains a list of recommended modules which should be selected for future maintenance and compatibility.\r\n\r\nFor example:\r\n\r\n* The [Entity API](https://www.drupal.org/project/entity) and modules must be used along with the [Entity metadata wrappers](https://www.drupal.org/documentation/entity-metadata-wrappers) for accessing and manipulating entities rather than the standard Drupal approach.\r\n* When using Date module, the Date (ISO format) must always be used and never Date or Date (Unix timestamp).\r\n\r\n## Multilingual Projects\r\n\r\nProjects requiring more than one language must install the base language the base language to be used as generic placeholders (eg. `form:username`), on top of which other languages are added, such as English, French, etc.\r\n\r\n# Drupal Features Development\r\n\r\nWFP projects make heavy use of [Features](https://www.drupal.org/project/features) to create self-contained collections of Drupal entities which satisfy a certain use-case.\r\n\r\nAll Features must follow the [Kit Specification](https://www.drupal.org/project/kit) and, when achieved, be declared [Kit Compliant](http://cgit.drupalcode.org/kit/tree/kitf.txt?id=c3717385435a4e9c59cb1ffa708a62628b0d6530#n54) by adding the following in the `.info` file\r\n\r\n```\r\n  kitf = \"1.0-draft\"\r\n```\r\n\r\nEach Feature must contain all relevant content types, base fields, instance fields, views, blocks, contexts, permissions, variables, image presets, taxonomies, menus, breadcrumbs, path configurations, descriptions, tags etc.\r\n\r\nAll project specific code being put inside of the `.module` file of Features.\r\n\r\nCorrect module dependencies must be assigned to each Features.\r\n\r\nAll variables and structures created for a Feature must have a corresponding deinstallation created in the Features [`.install`](https://www.drupal.org/node/876250) file.\r\n\r\n## Development of Custom Modules\r\n\r\nCustom module development is only required for functionality to be reusable across multiple projects. All modules must include a [composer.json](https://getcomposer.org/doc/04-schema.md#the-composer-json-schema) file.\r\n\r\n# Drupal Development Standards and Best Practice\r\n\r\nAll developers must strictly follow the Drupal Best Practices, including:\r\n\r\n* [Drupal Coding Standards](https://www.drupal.org/coding-standards)\r\n* [Programming best practices](https://www.drupal.org/node/287350)\r\n* Functions must be kept [short and easily readable](https://www.drupal.org/node/299074).\r\n* [Write secure code](https://www.drupal.org/writing-secure-code).\r\n* Must use appropriate [Drupal core hooks](https://api.drupal.org/api/drupal/includes!module.inc/group/hooks/7) when dealing with core.\r\n* [CSS standards](https://www.drupal.org/node/1886770).\r\n* [Web standards and accessibility](https://www.drupal.org/node/769692).\r\n* [Module documentation](https://www.drupal.org/node/161085).\r\n\r\nAll standards must be implemented before code changes are committed to the repository.\r\n\r\n## Project Security and Audits\r\n\r\nSecurity upgrades for core and contributes modules much be applied within 6 hours of being announced.\r\n\r\nIn each case a security vulnerability is discovered, it must be evaluated using the [Your Drupal site got hacked. Now what?](https://www.drupal.org/node/2365547) guide. The preferred method to deal with serious threats is the rollback approach.\r\n\r\nProject audits must be run on a regular basis on a clone of the production database and file system, using [Site Audit](https://www.drupal.org/project/site_audit), [Security Review](https://www.drupal.org/project/security_review), [Hacked!](https://www.drupal.org/project/hacked) and Diff modules via the following drush command from the root of the project:\r\n\r\n```\r\n./scripts/audit.sh\r\n```\r\n\r\n## Consistent Layout Approach\r\n\r\nA consistent and clear approach must be taken to [managing page and content layouts](http://www.slideshare.net/mobile/davexoxide/drupal-blocks-vs-context-vs-panels) which is scalable for future project development such:\r\n\r\n* Page Layouts: [Context](https://www.drupal.org/project/context), [Panels](https://www.drupal.org/project/panels), [Panels Everywhere](https://www.drupal.org/project/panels_everywhere).\r\n* Content Layouts: Panels , [Panelizer](https://www.drupal.org/project/panelizer), [Display Suite](https://www.drupal.org/project/ds) , [Entity view modes](https://www.drupal.org/project/entity_view_mode)\r\n\r\nUsing the standard Drupal theme regions and Blocks is discouraged.\r\n\r\n## No Code or Functionality Redundancy\r\n\r\nThe [DRY](http://en.wikipedia.org/wiki/Don't_repeat_yourself) approach must be adhered to in all aspects of the project, including custom code and module selection.\r\n\r\n## No Hard-Coded Variable Values\r\n\r\nNo hard-coding of potentially variable values is permitted, such as:\r\n\r\n* The domain of internal links, eg. use `/content` rather than `http://www.wfp.org/content`\r\n* URL Paths, eg. `/homepage` might change but `/node/2` is a unique identifier.\r\n\r\nAll custom modules, Features and theme must follow the [Drupal release naming conventions](https://www.drupal.org/node/1015226).\r\n\r\n## Database Queries\r\n\r\nWhen appropriate, database queries must use the [EntityFieldQuery](https://api.drupal.org/api/drupal/includes!entity.inc/class/EntityFieldQuery) class and never make calls using non-Drupal recommended approaches.\r\n\r\n## Patches\r\n\r\nAll project patches be stored in the `patches/` directory of the project codebase with their necessary information such as links to existing drupal.org discussion threads.\r\n\r\nDevelopers must [submit patches for Drupal core or contributed modules](https://www.drupal.org/patch/submit) to drupal.org with the expectation that the will be to the relevant issue queue with the idea that the functionality will be included in a future release.\r\n\r\nPatches must be applied using the [Composer Patches Plugin](https://github.com/netresearch/composer-patches-plugin).\r\n\r\nWorkarounds to bug or issues must be added to the code comments prefixed with a @todo and include a description and a link to the official issue report.\r\n\r\n# Drupal Theme Development\r\n\r\nThe role of the theme is purely visual, it is for adding extra styling and markup to the output.\r\n\r\n> \"Since a module is most intimately familiar with its own data and functionality, it's the module's responsibility to provide the default theme implementation. As long as the module uses the theme system properly, a theme will be able to override any HTML and CSS by hot-swapping its own implementation for the module's implementation.\"\r\n-- [Drupal 7 Module Development Theme Development](https://www.packtpub.com/books/content/drupal-7-module-development-drupals-theme-layer)\r\n\r\nBusiness logic and function calls are never allowed in `template.php` or `.tpl.php` template files, whether in the theme or in custom modules.\r\n\r\nAll Themes must follow the [Kit Specification](https://www.drupal.org/project/kit) and be Kit Compliant.\r\n\r\n## WFP Base Theme\r\n\r\nWFP branded projects must start with the WFP Base theme with project specific customisations being added to a new project [sub-theme](https://www.drupal.org/node/225125).\r\n\r\n# Caching & Performance\r\n\r\nAll code and architectures must implement an appropriate cache state and function correctly with Page and Basic caching is enabled, including for:\r\n\r\n* Drupal core caching: Page, [Block](https://api.drupal.org/api/drupal/includes!common.inc/group/block_caching), Form, Menu, Path, Field, etc.\r\n* Contributed module caches such as Views, Panels, Entity API, etc.\r\n* Caching systems such as Boost, AuthCache, Page Manager, MemCache, Redis, Varnish, etc.\r\n\r\nCaching expiration must be set for all Blocks, Views displays, etc.\r\n\r\nWhen appropriate, [Render cache](https://www.drupal.org/project/render_cache) and/or [Entity Cache](https://www.drupal.org/project/entitycache) must be used.\r\n\r\n> \"Never do something time consuming twice if you can hold onto the results and re-use them.\"\r\n-- [A Beginner's Guide to Caching Data in Drupal 7](https://www.lullabot.com/blog/article/beginners-guide-caching-data-drupal-7).\r\n\r\nMust make effective use of [drupal_static()](https://api.drupal.org/api/drupal/includes%21bootstrap.inc/function/drupal_static/7) for persistent caching within a single page request and [cache_get](https://api.drupal.org/api/drupal/includes%21cache.inc/function/cache_get/7)() and [cache_set()](https://api.drupal.org/api/drupal/includes%21cache.inc/function/cache_set/7) for persistent caching across multiple pages.\r\n\r\nAll code must work with Drupal core JS and CSS optimisation activated as well as for the module [Advanced CSS/JS Aggregation](https://www.drupal.org/project/advagg).\r\n\r\n# Revision Control\r\n\r\n\r\n\r\nAll [git tags](http://git-scm.com/book/en/v2/Git-Basics-Tagging) should follow the development roadmap as closely as possible, using the [Semantic Versioning](http://semver.org/) standards for tag naming.\r\n\r\nThe revision control history is as important as the code itself, therefore commit messages must be verbose and clearly describe the changes as well as being association with a relevant ticket.\r\n","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}