diff --git a/INSTALL.md b/INSTALL.md index aab400ad4..2b2288e0f 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,12 +1,5 @@ # BLT installation and updates -* System requirements -* [Creating a new project with BLT](#creating-new) -* [Adding BLT to an existing project](#existing-project) -* [Updating to the latest version of BLT](#updating) - * [Updating from a non-composer-managed version](#update-non-composered) - * [Updating a composer-managed version](#update-composered) - ## System Requirements You should be able to use the following tools on the command line of your native operating system: @@ -23,40 +16,37 @@ You should be able to use the following tools on the command line of your native * Globally install pretissimo for parallelized composer downloads: - ``` - composer global require "hirak/prestissimo:^0.3" - ``` + composer global require "hirak/prestissimo:^0.3" + * If you have xDebug enabled for your PHP CLI binary, it is highly recommended that you disable it to dramatically improve performance. -## Creating a new project with BLT +## Creating a new project with BLT 1. Create a new project using the [blt-project](https://github.com/acquia/blt-project) template: - ``` - composer create-project acquia/blt-project:8.x-dev MY_PROJECT --no-interaction - cd MY_PROJECT - ``` + composer create-project acquia/blt-project:8.x-dev MY_PROJECT --no-interaction + cd MY_PROJECT + 1. Install the `blt` alias and follow on-screen instructions: - ``` - ./vendor/bin/blt install-alias - ``` + ./vendor/bin/blt install-alias + 1. Customize BLT configuration files: - * `project.yml` - * `docroot/sites/default/settings/local.settings.php` - * Add your local DB credentials to `$databases` + * `project.yml` + * `docroot/sites/default/settings/local.settings.php` + * Add your local DB credentials to `$databases` 1. Replace tokens in new BLT-generated files with your custom values in project.yml: - ``` - blt configure - ``` + + blt configure + 1. (optional) Modify project files. Important files that you may want to modify include: - * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here. - * Project’s root README.md. - * Other project documentation in the readme directory. + * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here. + * Project’s root README.md. + * Other project documentation in the readme directory. 1. (optional) Follow instructions for installing Drupal locally. -## Adding BLT to an existing project +## Adding BLT to an existing project To add BLT to a pre-existing Drupal project, do the following: @@ -64,58 +54,52 @@ To add BLT to a pre-existing Drupal project, do the following: 1. If you currently manage your dependencies via Composer, ensure that they are all up to date via `composer update`. Assert that these updates do not break your project. 1. `cd` into your existing project directory. 1. Add BLT via composer and initialize it: - ``` - composer require acquia/blt:~8 - ./vendor/acquia/blt/blt.sh init - ``` + + composer require acquia/blt:~8 + ./vendor/acquia/blt/blt.sh init + 1. (optional) Modify project files. Important files that you may want to modify include: - * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here. - * Project’s root README.md. - * Other project documentation in the readme directory. + * composer.json. Note that Drupal core, contrib, and third party dependencies are all managed here. + * Project’s root README.md. + * Other project documentation in the readme directory. 1. (optional) Follow instructions for installing Drupal locally. -## Updating BLT +## Updating BLT -### Updating a composer-managed version +### Updating a composer-managed version If you are already using BLT via Composer, you can update to the latest version of BLT by running the following commands from your project's root directory: -``` -composer update acquia/blt -blt update -``` + composer update acquia/blt + blt update + -### Updating from a non-Composer-managed version +### Updating from a non-Composer-managed version If you are using an older version of BLT that was not installed using Composer, you may update to the Composer-managed version by running the following commands: 1. Remove any dependencies that may conflict with upstream acquia/blt. You may add these back later after the upgrade, if necessary. - ``` - composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --no-interaction --no-update - composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --dev --no-interaction --no-update - composer config minimum-stability dev - ``` + composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --no-interaction --no-update + composer remove drush/drush drupal/console phing/phing phpunit/phpunit squizlabs/php_codesniffer symfony/yaml drupal/coder symfony/console --dev --no-interaction --no-update + composer config minimum-stability dev + 1. (conditional) If you are using Lightning, verify that your version constraint allows it to be updated to the latest stable version: - ``` - composer require drupal/lightning:~8 --no-update - ``` + composer require drupal/lightning:~8 --no-update + 1. Require acquia/blt as a dev dependency: - ``` - composer require acquia/blt:~8 --dev --no-update - ``` + composer require acquia/blt:~8 --dev --no-update + 1. Update all dependencies: - ``` - composer update - ``` + composer update + 1. Execute update script: - ``` - ./vendor/acquia/blt/scripts/blt/convert-to-composer.sh - ``` + ./vendor/acquia/blt/scripts/blt/convert-to-composer.sh + Note that all of the steps from this point forward are the same steps that would be used by a newly onboarded developer setting up your existing project on their local machine for the first time. @@ -124,16 +108,17 @@ Note that all of the steps from this point forward are the same steps that would Before building your project dependencies and installing Drupal, you must have a fully functional \*AMP stack on your local machine. BLT intentionally does not provide this local development environment--that is outside of the scope of BLT’s intended responsibilities. It does, however, make recommendations for which tools you should use to manage your stack. Please see [Local Development](template/readme/local-development.md) for more information on setting up your \*AMP stack: - * [Acquia Dev Desktop](template/readme/local-development.md#using-acquia-dev-desktop-for-blt-generated-projects) - * [Drupal VM](template/readme/local-development.md#using-drupal-vm-for-blt-generated-projects) - * [Other](https://github.com/acquia/blt/blob/8.x/template/readme/local-development.md#alternative-local-development-environments) + +* [Acquia Dev Desktop](template/readme/local-development.md#using-acquia-dev-desktop-for-blt-generated-projects) +* [Drupal VM](template/readme/local-development.md#using-drupal-vm-for-blt-generated-projects) +* [Other](https://github.com/acquia/blt/blob/8.x/template/readme/local-development.md#alternative-local-development-environments) When you have completed setting up your local \*AMP stack, double check that the following pieces of information are still correct: * Local site DB credentials: `$databases` in docroot/sites/default/settings/local.settings.php * Local site URL: `$options[‘uri’]` in docroot/sites/default/local.drushrc.php -## Build your project’s local dependencies and install Drupal locally +## Build your project’s local dependencies and install Drupal locally Run the following command from the project root: `blt local:setup`. This will do a lot of things for you, including: diff --git a/mkdocs.yml b/mkdocs.yml index 519583fc5..ad23284f9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,24 +11,29 @@ markdown_extensions: pages: - Home: 'index.md' - Overview: 'README.md' - - Getting started: 'INSTALL.md' + - Getting started: + - Installation & upgrade: 'INSTALL.md' - Local development: 'template/readme/local-development.md' - - Project documentation: 'template/README.md' + - Project documentation: + - Overview: 'template/README.md' - Developer: - Onboarding: 'template/readme/onboarding.md' - Repository architecture: 'template/readme/repo-architecture.md' - - Running project tasks: 'template/readme/project-tasks.md' + - Running project tasks: + - Overview: 'template/readme/project-tasks.md' - Patches: 'template/patches/README.md' - - Drush: 'template/drush/README.MD' - - Git hooks: 'scripts/git-hook/README.md' - - Best practices: 'template/readme/best-practices.md' + - Drush: 'template/drush/README.md' + - Git hooks: 'template/scripts/git-hooks/README.md' + - Best practices: + - Overview: 'template/readme/best-practices.md' - Views: 'template/readme/views.md' - Workflow: 'template/readme/dev-workflow.md' - Automated testing: 'template/tests/README.md' - Technical Architect: - Project architecture document: 'template/readme/architecture.md' - Deploying to cloud: 'template/readme/deploy.md' - - Release process: 'template/readme/release-process.md' + - Releases: + - Release process: 'template/readme/release-process.md' - Release notes: 'scripts/release-notes/README.md' - Setting up continuous integration: 'template/readme/ci.md' - Open source contribution: 'template/readme/os-contribution.md' diff --git a/template/readme/best-practices.md b/template/readme/best-practices.md index 45cad3ef1..dfd3a0bd2 100644 --- a/template/readme/best-practices.md +++ b/template/readme/best-practices.md @@ -4,27 +4,18 @@ _This document is a work in progress._ Unlinked items are planned topics, feel free to contribute. -* [Standards](#standards) -* [Exporting configuration](#exporting-config) -* [Configuration updates](#config-updates) -* [Caching strategies](#caching) -* [Patching](#patching) -* [Building Views](#views) -* [Logging](#logging) -* [Building content types](#content-types) - -## Standards +## Standards All work must conform to established best practices and coding standards. Code quality is ensured in a variety of ways: -* All code must conform to [Drupal Coding Standards](https://www.drupal.org/coding-standards). This is enforced via [local git hooks](../scripts/git-hooks/README.md) and [code checks](../build/ performed during continuous integration. +* All code must conform to [Drupal Coding Standards](https://www.drupal.org/coding-standards). This is enforced via [local git hooks](../scripts/git-hooks/README.md) and code checks performed during continuous integration. * All front end code must follow Drupal Theming Best Practices. * All code must be reviewed by a peer or established integrator before being merged into the master branch. * All new features must covered by an automated test that mirrors the ticket acceptance criteria. Please peruse the [examples](examples) directory for examples of various coding best practices. -## Exporting configuration +## Exporting configuration All site functionality should be represented in version-controlled code. This includes all configuration. Drupal configuration is typically exported via [Features](https://www.drupal.org/project/features). @@ -53,7 +44,7 @@ Common mistakes: * 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 +## 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()` @@ -62,7 +53,7 @@ Common mistakes: * 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 +## 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_. @@ -89,24 +80,25 @@ Specifically, ensure that you are properly caching data at every level possible, See the [Drupal 8 Cache API](https://www.drupal.org/developing/api/8/cache) documentation for information in implementing your caching strategy. -## Patching +## 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 +## Views Please see [views.md](views.md). -## Logging +## Logging -* Any configuration changes from custom modules should be logged to watchdog (also [Acquia Library recommendations|https://docs.acquia.com/articles/how-audit-authenticated-user-actions-better-risk-management]) +* Any configuration changes from custom modules should be logged to watchdog (also [Acquia Library recommendations](https://docs.acquia.com/articles/how-audit-authenticated-user-actions-better-risk-management) * Any destructive actions **must** be logged -## Building content types +## Building content types @todo Document: + * Appropriate time to use fields * Audit for overly complex content types * Reason: All fields loaded for each node load diff --git a/template/readme/ci.md b/template/readme/ci.md index 2b30bf836..75ccce5ab 100644 --- a/template/readme/ci.md +++ b/template/readme/ci.md @@ -1,4 +1,4 @@ -## Continuous Integration +## Continuous Integration Integration with Travis CI is included, although Phing tasks can be used with any CI tool. The default Travis CI build process is as follows: @@ -21,17 +21,15 @@ Automated testing of live content is easy to set up with two simple steps: 1. Add the hostname of your staging server to .travis.yml: - ``` - ssh_known_hosts: - - staging-12345.prod.hosting.acquia.com - ``` + ssh_known_hosts: + - staging-12345.prod.hosting.acquia.com + 2. Override the default `ci:build:validate:test` target by adding the following to `build/custom/phing/build.xml`: - ``` - - - ``` + + + ### Setting Up Travis CI for automated deployments @@ -46,31 +44,26 @@ To set up this workflow, you must configure Acquia Cloud, GitHub, and Travis CI 1. Generate an SSH key locally. E.g., - ``` - cd ~/.ssh - ssh-keygen -t rsa -b 4096 - ``` + cd ~/.ssh + ssh-keygen -t rsa -b 4096 Do not use a passphrase! + 1. Create a new Acquia Cloud account to be used exclusively as a container for the SSH keys that will grant Travis push access to Acquia Cloud. This can be done by inviting a new team member on the "Teams" tab in Acquia Cloud. You can use an email address like `+travis@acquia.com`. The team member must have SSH push access. 1. Login the your new Acquia Cloud account and add the public SSH key from the key pair that was generated in step 1 by visiting `https://accounts.acquia.com/account/[uid]/security`. 1. Add the same public SSH key to the "Deployment Keys" section on your project's GitHub settings page, located at `https://github.com/acquia-pso/[project-name]/settings/keys`. 1. Add the _private SSH key_ to your project's Travis CI settings located at `https://magnum.travis-ci.com/acquia-pso/[project-name]/settings`. 1. Uncomment the example deployment steps in your .travis.yml file and customize them to deploy your desired branch. 1. Add your cloud git repository to the remotes section of your project.yml file: - - ``` - remotes: - - example@svn-14671.prod.hosting.acquia.com:example.git` - ``` + + remotes: + - example@svn-14671.prod.hosting.acquia.com:example.git` 1. Add your cloud git repository's server host name to `ssh_known_hosts` in your .travis.yml file. - ``` - addons: - ssh_known_hosts: - - svn-14671.prod.hosting.acquia.com - ``` + addons: + ssh_known_hosts: + - svn-14671.prod.hosting.acquia.com 1. Commits or merges to the develop branch on GitHub should now trigger a fully built artifact to be deployed to your specified remotes. diff --git a/template/readme/deploy.md b/template/readme/deploy.md index defd4c9c5..920fb9165 100644 --- a/template/readme/deploy.md +++ b/template/readme/deploy.md @@ -33,7 +33,7 @@ This task is analogous to `setup:build` but with a few critical differences: After the artifact is created, you can inspect it or even run it as a website locally. You may also manually commit and push it to ACE. -## Create and deploy the build artifact +## Create and deploy the build artifact To both create and deploy the build artifact in a single command, run the following command diff --git a/template/readme/local-development.md b/template/readme/local-development.md index 445aa9ff3..829694fbf 100644 --- a/template/readme/local-development.md +++ b/template/readme/local-development.md @@ -2,8 +2,8 @@ Acquia currently recommends the use of either: - * [Drupal VM](#drupal-vm): An isolated virtual machine, built with Vagrant and Ansible. - * [Acquia Dev Desktop](#dd): A turn-key LAMP stack tailored specifically for Acquia-hosted Drupal sites. + * [Drupal VM](#using-drupal-vm-for-blt-generated-projects): An isolated virtual machine, built with Vagrant and Ansible. + * [Acquia Dev Desktop](#acquia-dev-desktop): A turn-key LAMP stack tailored specifically for Acquia-hosted Drupal sites. No matter what local environment you choose to use, the following guidelines should be followed: @@ -23,7 +23,7 @@ If you must use Windows, we recommend that: * [cmder](http://cmder.net/) * [cygwin](https://www.cygwin.com/) -## Using Drupal VM for BLT-generated projects +## Using Drupal VM for BLT-generated projects _BLT support for Drupal VM is experimental. Not all BLT features currently work with Drupal VM. Additionally, Drupal VM integration with BLT cannot be tested via Travis CI, and is prone to regressions._ @@ -54,7 +54,7 @@ To execute Behat tests using the 'drupal' driver on a Drupal VM environment, you You may choose to write only behat tests that utilize the Drupal Extension's "drupal" driver. Doing this will allow you to run `blt tests:behat` from the host machine without modificaitons to the Behat local.yml configuration. -## Using Acquia Dev Desktop for BLT-generated projects +## Using Acquia Dev Desktop for BLT-generated projects ### Project creation and installation changes @@ -66,17 +66,14 @@ In order to use a custom version of Drush (required by BLT) with Dev Desktop, yo 1. Add the following lines to `~/.bash_profile`: - ``` - export PATH="/Applications/DevDesktop/mysql/bin:$PATH" - export DEVDESKTOP_DRUPAL_SETTINGS_DIR="~/.acquia/DevDesktop/DrupalSettings" - - ``` + export PATH="/Applications/DevDesktop/mysql/bin:$PATH" + export DEVDESKTOP_DRUPAL_SETTINGS_DIR="~/.acquia/DevDesktop/DrupalSettings" + 1. Ensure that Dev Desktop's PHP binary is being used on the CLI. You can check this via `which php`. 1. Enable the usage of environmental variables by adding the following line to `php.ini`, which you can locate with `php --ini`: - ``` - variables_order = "EGPCS" - ``` + variables_order = "EGPCS" + 1. Restart your terminal session after making the aforementioned changes. ## Alternative local development environments @@ -85,10 +82,10 @@ For reasons, some teams may prefer to use a different development environment. D It is up to each team to choose how to handle local development, but some of the main things that help a project's velocity with regard to local development include: - - Uniformity and the same configuration across all developer environments. - - Ease of initial environment configuration (if it takes more than an hour to get a new developer running your project locally, you're doing it wrong). - - Ability to emulate all aspects of the production environment with minimal hassle (e.g. Varnish, Memcached, Solr, Elasticsearch, different PHP versions, etc.). - - Helpful built-in developer tools (e.g. XHProf, Xdebug, Adminer, PimpMyLog). - - Ease of use across Windows, Mac, or Linux workstations. +* Uniformity and the same configuration across all developer environments. +* Ease of initial environment configuration (if it takes more than an hour to get a new developer running your project locally, you're doing it wrong). +* Ability to emulate all aspects of the production environment with minimal hassle (e.g. Varnish, Memcached, Solr, Elasticsearch, different PHP versions, etc.). +* Helpful built-in developer tools (e.g. XHProf, Xdebug, Adminer, PimpMyLog). +* Ease of use across Windows, Mac, or Linux workstations. If you choose to use a different solution than recommended here, please make sure it fits all the needs of your team and project, and will not be a hindrance to project development velocity! diff --git a/template/readme/onboarding.md b/template/readme/onboarding.md index fe30449d7..1dcf83b99 100644 --- a/template/readme/onboarding.md +++ b/template/readme/onboarding.md @@ -44,19 +44,13 @@ If you need to make requests via a proxy server, please [configure git to use a 1. [Fork](https://help.github.com/articles/fork-a-repo) the primary GitHub repository 1. Clone your fork to your local machine: - ``` - git clone git@github.com:username/project-repo.git -b develop - git remote add upstream git@github.com:acquia-pso/project-repo.git - ``` + git clone git@github.com:username/project-repo.git -b develop + git remote add upstream git@github.com:acquia-pso/project-repo.git 1. Checkout the `develop` branch. `git checkout develop` 1. Run `composer install` (you must already have Composer installed). -1. Run `blt setup:drupal:settings` This will generate - `docroot/sites/default/settings/local.settings.php` and - `docroot/sites/default/local.drushrc.php`. Update these with your local - database credentials and your local site URL. -1. Run `blt local:setup`. This will build all project dependencies and install - drupal. +1. Run `blt setup:drupal:settings` This will generate `docroot/sites/default/settings/local.settings.php` and `docroot/sites/default/local.drushrc.php`. Update these with your local database credentials and your local site URL. +1. Run `blt local:setup`. This will build all project dependencies and install drupal. 1. Create and edit your local drush alias file. Copy `drush/site-aliases/example.local.aliases.drushrc.php` to `drush/site-aliases/local.aliases.drushrc.php`. Edit the new alias file with your local path. After this initial setup, you should only need to run `blt setup:build` when composer.json is updated, and `blt local:drupal:install` when you need to reinstall the site. diff --git a/template/readme/project-tasks.md b/template/readme/project-tasks.md index 029c97381..a57a76fe7 100644 --- a/template/readme/project-tasks.md +++ b/template/readme/project-tasks.md @@ -2,14 +2,7 @@ “how do I _____ on my local machine?” -* [(re)Install Drupal](#install-drupal) -* [Update dependencies (module, theme, core, etc.)](#update-dependency) -* [Patch a project](#patch) -* [Deploy to cloud](#deploy) -* [Run tests & code validation](#tests) -* [Build frontend assets](#frontend) - -## (re)Install Drupal +## (re)Install Drupal Pre-requisites to installation: @@ -19,7 +12,7 @@ Pre-requisites to installation: To re-install Drupal, execute: `blt setup:drupal:install`. Note that this will drop the existing database tables and install Drupal from scratch! -## Update dependencies (core, profile, module, theme, libraries) +## Update dependencies (core, profile, module, theme, libraries) Composer should be used to manage Drupal core, all contributed dependencies, and most third party libraries. The primary exception to this is front end libraries that may be managed via a front-end specific dependency manager, such as [Bower](http://bower.io/) or [NPM](https://www.npmjs.com/). @@ -50,15 +43,15 @@ To update drupal core: 4. Use git to review changes to committed files. E.g., changes to .htaccess, robots.txt, etc. 5. Add and commit desired changes. -## Patch a project +## Patch a project Please see [patches/README.md](../patches/README.md) for information on patch naming, patch application, and patch contribution guidance. -## Deploy to cloud +## Deploy to cloud Please see [Deploy](deploy.md) for a detailed description of how to deploy to Acquia Cloud. -## Run tests & code validation +## Run tests & code validation Please see [tests/README.md](../tests/README.md) for information on running tests. @@ -68,7 +61,7 @@ To execute PHP codesniffer and PHP lint against the project codebase, run: blt validate:all ``` -## Build front end assets +## Build front end assets Ideally, you will be using a theme that uses SASS/SCSS, a styleguide, and other tools that require compilation. Like dependencies, the compiled assets should not be directly committed to the project repository. Instead, they should be built during the creation of a production-ready build artifact. @@ -98,7 +91,7 @@ This command will be executed when dependencies are built in a local or CI envir blt frontend:build ``` -## Updating your local environment +## Updating your local environment The project is configured to update the local environment with a local drush alias and a remote alias as defined in `project.yml` or `project.local.yml`. Given that these aliases match, those in `drush/site-aliases/`, you can update the site with BLT. Please see [drush/README.md](../drush/README.md) for details on how to create these aliases. diff --git a/template/readme/release-process.md b/template/readme/release-process.md index 490806b9c..c70dff6db 100644 --- a/template/readme/release-process.md +++ b/template/readme/release-process.md @@ -1,33 +1,24 @@ # Release Process -This document is a work in progress. - -* [Generating a build artifact](#build-artifact) -* [Branching strategies](#branching) -* [Tagging](#tagging) -* [Release Notes](#release-notes) -* [Deploying tag and executing updates](#deploy-tag) -* [Notifications](#notifications) (slack, hipchat, etc) - -## Branching strategies +## Branching strategies @todo Document this! -## Generating a build artifact +## Generating a build artifact -See [Create and deploy the build artifact](deploy.md#build-artifact) in [deploy.md](deploy.md). +See [Create and deploy the build artifact](deploy.md#create-and-deploy-the-build-artifact) in [deploy.md](deploy.md). -## Tagging +## Tagging @todo Document this! -## Release notes +## Release notes Each release should be accompanied by a set of release notes, which can be easily generated using the [Release Notes Script](../scripts/release-notes/README.md). This script will automatically aggregate all of the descriptions from Pull Requests since a specified date. The generated tet aggregate can then be copied and pasted into release notes on GitHub. -## Deploying tag and executing updates +## Deploying tag and executing updates Deploying Drupal across environments can be daunting, but if due diligence has been taken with configuration management, the process of deployment is actually quite simple. @@ -48,7 +39,7 @@ A few things that you should (almost) never do on production: There might be some extra steps depending on the infrastructure and the extent of site changes. For example, a major application change might require a flush of other caches in the system such as Varnish or Memcached. -# Notifications +# Notifications You can configure various tools to provide notifications of deployment related events. For instance: diff --git a/template/readme/views.md b/template/readme/views.md index 2ac4fba9b..71bd76098 100644 --- a/template/readme/views.md +++ b/template/readme/views.md @@ -5,23 +5,23 @@ The following are guidelines for building new views. * _Caching_ - * For all public facing views, always use some form of caching. A non time-based cache is preferable because it often permits the longest cache lifetimes, and invalidates caches only when necessary. Possible options are: - * [Views content cache](https://www.drupal.org/project/views_content_cache) - * [Views argument cache](https://www.drupal.org/project/views_arg_cache) - * Time based + * For all public facing views, always use some form of caching. A non time-based cache is preferable because it often permits the longest cache lifetimes, and invalidates caches only when necessary. Possible options are: + * [Views content cache](https://www.drupal.org/project/views_content_cache) + * [Views argument cache](https://www.drupal.org/project/views_arg_cache) + * Time based * _Pagination_ - * Always specify either a fixed number of results or a pager. Never display all results. - * Whenever possible, use Views lite pager rather than a full pager. - * Note that this is unfortunately mutually exclusive with caching due to bugs in Views Lite Pager. @see https://www.drupal.org/node/2285591. + * Always specify either a fixed number of results or a pager. Never display all results. + * Whenever possible, use Views lite pager rather than a full pager. + * Note that this is unfortunately mutually exclusive with caching due to bugs in Views Lite Pager. @see https://www.drupal.org/node/2285591. * _Advanced_ - * Always add a semantically descriptive machine name to views displays. E.g., use `press_releases_all` rather than `page_1`. This makes all PHP, CSS, and JS related to the view display more readable. + * Always add a semantically descriptive machine name to views displays. E.g., use `press_releases_all` rather than `page_1`. This makes all PHP, CSS, and JS related to the view display more readable. * _Relationships_ - * Whenever possible, use "require this relationship" for all views relationships. This causes views to perform an inner join rather than a left join, and is almost always faster. - * Never use the `Taxonomy Terms on Node` relationship or filter. Instead, use a relationship or filter for the specific taxonomy reference field. This has a tremendous performance impact. + * Whenever possible, use "require this relationship" for all views relationships. This causes views to perform an inner join rather than a left join, and is almost always faster. + * Never use the `Taxonomy Terms on Node` relationship or filter. Instead, use a relationship or filter for the specific taxonomy reference field. This has a tremendous performance impact. * _Filters_ - * For all exposed filters, manually set the fitler identifier to something end-user friendly. This should not contain drupalisms. E.g., use `type` rather than `field_type`. + * For all exposed filters, manually set the fitler identifier to something end-user friendly. This should not contain drupalisms. E.g., use `type` rather than `field_type`. * _No Results Behavior_ - * Always add "No Results behavior" of some type. This is typically text informing that user that no results were found. + * Always add "No Results behavior" of some type. This is typically text informing that user that no results were found. @todos: diff --git a/template/tests/README.md b/template/tests/README.md index 409c3572c..e206481f0 100644 --- a/template/tests/README.md +++ b/template/tests/README.md @@ -65,7 +65,7 @@ This directory contains all projects tests, grouped by testing technology. For a ├── jmeter - contains all jMeter tests └── phpunit - contains all PHP Unit tests -## Executing tests +## Executing tests Before attempting to execute any tests, verify that composer dependencies are built by running `composer install` in the project root. @@ -85,7 +85,7 @@ For more information on the commands, run: * `./vendor/bin/phpunit --help` * `./vendor/bin/behat --help` -## Behat +## Behat The high-level purpose BDD is to create a strong connection between business requirements and the actual tests. Behat tests should mirror ticket acceptance criteria as closely as possible. @@ -144,7 +144,7 @@ PHP based BDD library. Best practices for tests writing apply to both * [The training wheels came off](http://aslakhellesoy.com/post/11055981222/the-training-wheels-came-off) -## PHPUnit +## PHPUnit Project level, functional PHPUnit tests are included in `tests/phpunit`. Any PHPUnit tests that affect specific modules or application level features should be placed in the same directory as that module, not in this directory.