Merge remote-tracking branch 'upstream/master' into 10.x

# Conflicts:
#	CONTRIBUTING.md
#	README.md
#	docs/commands.md
#	docs/install.md
#	examples/Commands/ArtCommands.php
#	examples/Commands/PolicyCommands.php
#	src/TestTraits/DrushTestTrait.php
#	tests/README.md

CONTRIBUTING.md

@@ -7,15 +7,15 @@ Drush is built by people like you! Please [join us](https://github.com/drush-ops
 * Contributions are submitted, reviewed, and accepted using GitHub pull requests.
 * The latest changes are in the `10.x` branch. PR's should initially target this branch.
 * Try to make clean commits that are easily readable (including descriptive commit messages!)
-* See the test-specific [README.md](https://github.com/drush-ops/drush/blob/10.x/docs/contribute/unish.md) for instructions on running the test suite. Test before you push. Get familiar with Unish, our test suite. Optionally run tests in the provided Docker containers.
+* See the test-specific [README.md](https://github.com/drush-ops/drush/blob/10.x/tests/README.md) for instructions on running the test suite. Test before you push. Get familiar with Unish, our test suite. Optionally run tests in the provided Docker containers.
 * We maintain branches named 10.x, 9.x, etc. These are release branches. From these branches, we make new tags for patch and minor versions.
 
 ## Development Environment
 * You may choose to use the docker-compose file in root directory for an optimized environment.
 * See `composer run-script -l` for a list of helper scripts.
 
 ## Coding style
-* Do write comments. You don't have to comment every line, but if you come up with something that's a bit complex/weird, just leave a comment. Bear in mind that you will probably leave the project at some point and that other people will read your code. Undocumented huge amounts of code are nearly worthless!
+* Do write comments. You don't have to comment every line, but if you come up with something that'sZ a bit complex/weird, just leave a comment. Bear in mind that you will probably leave the project at some point and that other people will read your code. Undocumented huge amounts of code are nearly worthless!
 * We use [PSR-2](https://www.php-fig.org/psr/psr-2/) in the /src directory. [Drupal's coding standards](https://drupal.org/coding-standards) are still used in the includes directory (deprecated code).
 * Keep it compatible. Do not introduce changes to the public API, or configurations too casually. Don't make incompatible changes without good reasons!
 

README.md

@@ -7,13 +7,13 @@ Drush is a command line shell and Unix scripting interface for Drupal. Drush cor
 
 Resources
 -----------
-* [Installing and Upgrading](https://www.drush.org/install) ([Drush 8](https://docs.drush.org/en/8.x/install/))
-* [General Documentation](https://www.drush.org/usage) ([Drush 8](https://docs.drush.org/en/8.x/install/))
-* [Drush Commands](https://www.drush.org/commands/10.x/all)
-* [API Documentation](https://www.drush.org/api/10.x)
+* [Installing and Upgrading](install.md) ([Drush 8](https://docs.drush.org/en/8.x/install/))
+* [General Documentation](usage.md) ([Drush 8](https://docs.drush.org/en/8.x/install/))
+* [Drush Commands](commands/10.x/all.md)
+* [API Documentation](/api/10.x/index.html)
 * [Drush packages available via Composer](https://packagist.org/search/?type=drupal-drush)
 * [A list of modules that include Drush integration](https://www.drupal.org/project/project_module?f[2]=im_vid_3%3A4654&solrsort=ds_project_latest_release+desc)
-* Drush comes with a [full test suite](https://github.com/drush-ops/drush/blob/10.x/docs/contribute/unish.md) powered by [PHPUnit](https://github.com/sebastianbergmann/phpunit). Each commit gets tested by our CI bots.
+* Drush comes with a [full test suite](https://github.com/drush-ops/drush/blob/10.x/tests/README.md) powered by [PHPUnit](https://github.com/sebastianbergmann/phpunit). Each commit gets tested by our CI bots.
 
 Support
 -----------
@@ -36,6 +36,10 @@ Some people pronounce the *dru* with a long 'u' like Dr*u*pal. Fidelity points
 go to them, but they are in the minority. Most pronounce Drush so that it
 rhymes with hush, rush, flush, etc. This is the preferred pronunciation.
 
+#### Does Drush have unit tests?
+Drush has an excellent suite of unit tests. See [tests/README.md](https://github.com/drush-ops/drush/blob/10.x/tests/README.md) for more information.
+
+
 Credits
 -----------
 
@@ -44,5 +48,5 @@ Credits
 * Redesigned by [Franz Heinzmann](http://unbiskant.org) in May 2007 for Drupal 5.
 * Thanks to [JetBrains](https://www.jetbrains.com) for [supporting this project and open source software](https://www.jetbrains.com/buy/opensource/).
 
-![Drush Logo](drush_logo-black.png)
-[![PhpStorm Logo](misc/icon_PhpStorm.png)](https://www.jetbrains.com/phpstorm/)
+![Drush Logo](img/drush_logo-black.png)
+[![PhpStorm Logo](img/icon_PhpStorm.png)](https://www.jetbrains.com/phpstorm/)

docs/commands.md

@@ -9,7 +9,7 @@ Creating a new Drush command or porting a legacy command is easy. Follow the ste
 1. Drush will then report that it created a commandfile, a drush.services.yml file and a composer.json file. Edit those files as needed.
 1. Use the classes for the core Drush commands at [/src/Drupal/Commands](https://github.com/drush-ops/drush/tree/10.x/src/Drupal/Commands) as inspiration and documentation.
 1. See the [dependency injection docs](dependency-injection.md) for interfaces you can implement to gain access to Drush config, Drupal site aliases, etc.
-1. Write PHPUnit tests based on [Drush Test Traits](https://github.com/drush-ops/drush/blob/10.x/docs/contribute/unish.md#drush-test-traits).
+1. Write PHPUnit tests based on [Drush Test Traits](https://github.com/drush-ops/drush/tree/10.x/tests#drush-test-traits).
 1. Once your two files are ready, run `drush cr` to get your command recognized by the Drupal container.
 
 ## Specifying the Services File

docs/install.md

@@ -21,53 +21,60 @@ Drupal Compatibility
 <table>
   <tr>
     <th rowspan="2"> Drush Version </th> 
-    <th rowspan="2"> PHP Version</th>
-    <th rowspan="2"> End Of Life </th>
+    <th rowspan="2"> Drush Branch </th>
+    <th rowspan="2"> PHP </th>
+    <th rowspan="2"> EOL </th>
     <th colspan="5"> Drupal versions </th>
   </tr>
-    <th>7</th> <th>-8.3</th> <th>8.4+</th> <th>9</th>
+    <th>6</th> <th>7</th> <th>-8.3</th> <th>8.4+</th> <th>9</th>
   </tr>
   <tr>
     <td> Drush 10 </td>
+    <td> 10.x </td>
     <td> 7.1+ </td>
     <!-- Released Oct 2019 -->
     <td> <i>TBD</i> </td>
-    <td></td> <td></td> <td>✅</td> <td><b>✅</b></td>
+    <td></td> <td></td> <td></td> <td>✅</td> <td><b>✅</b></td>
   </tr>
   <tr>
     <td> Drush 9 </td>
+    <td> 9.x </td>
     <td> 5.6+ </td>
     <!-- Released Jan 2018 -->
     <td> <i>May 2020</i> </td>
-    <td></td> <td></td> <td>✓</td> <td></td>
+    <td></td> <td></td> <td></td> <td>✅</td> <td></td>
   </tr>
   <tr>
     <td> Drush 8 </td>
+    <td> 8.x </td>
     <td> 5.4.5+ </td>
     <!-- Released Nov 2015 -->
     <td> ❶ </td>
-    <td>✅</td> <td>✅</td> <td><b>⚠️</b></td> <td></td>
+    <td>✅</td> <td>✅</td> <td>✅</td> <td><b>⚠️</b></td> <td></td>
   </tr>
   <tr>
     <td> Drush 7 </td>
+    <td> 7.x </td>
     <td> 5.3.0+ </td>
     <!-- Released May 2015 -->
     <td> Jul 2017 </td>
-    <td>✓</td> <td></td> <td></td> <td></td>
+    <td>✓</td> <td>✓</td> <td></td> <td></td> <td></td>
   </tr>
   <tr>
     <td> Drush 6 </td>
+    <td> 6.x </td>
     <td> 5.3.0+ </td>
     <!-- Released Aug 2013 -->
     <td> Dec 2015 </td>
-    <td>✓</td> <td></td> <td></td> <td></td>
+    <td>✓</td> <td>✓</td> <td></td> <td></td> <td></td>
   </tr>
   <tr>
     <td> Drush 5 </td>
+    <td> 5.x </td>
     <td> 5.2.0+ </td>
     <!-- Released March 2012 -->
     <td> May 2015 </td>
-    <td>✓</td> <td></td> <td></td> <td></td>
+    <td>✓</td> <td>✓</td> <td></td> <td></td> <td></td>
   </tr>
 </table>
 

examples/Commands/ArtCommands.php

@@ -23,7 +23,7 @@
  * This file is a good example of the first of those bullets (a commandfile) but
  * since it isn't part of a module, it does not implement drush.services.yml.
  *
- * See [Drush Test Traits](https://github.com/drush-ops/drush/blob/10.x/docs/contribute/unish.md#about-the-test-suites) for info on testing Drush commands.
+ * See [Drush Test Traits](https://github.com/drush-ops/drush/blob/10.x/tests/README.md#about-the-test-suites) for info on testing Drush commands.
  */
 
 class ArtCommands extends DrushCommands implements CustomEventAwareInterface

examples/Commands/PolicyCommands.php

@@ -8,7 +8,7 @@
 /**
  * Load this commandfile using the --include option - e.g. `drush --include=/path/to/drush/examples`
  *
- * See [Drush Test Traits](https://github.com/drush-ops/drush/blob/10.x/docs/contribute/unish.md#about-the-test-suites) for info on testing Drush commands.
+ * See [Drush Test Traits](https://github.com/drush-ops/drush/blob/10.x/tests/README.md#about-the-test-suites) for info on testing Drush commands.
  */
 
 class PolicyCommands extends DrushCommands

src/TestTraits/DrushTestTrait.php

@@ -5,7 +5,7 @@
  * DrushTestTrait provides a `drush()` method that may be
  * used to write functional tests for Drush extensions.
  *
- * More information is available at https://github.com/drush-ops/drush/blob/10.x/docs/contribute/unish.md#drush-test-traits.
+ * More information is available at https://github.com/drush-ops/drush/tree/10.x/tests#drush-test-traits.
  */
 trait DrushTestTrait
 {

tests/README.md

@@ -1 +1,52 @@
-Learn more about Unish, Drush's test suite, at https://www.drush.org/contribute
+---
+edit_url: https://github.com/drush-ops/drush/blob/10.x/tests/README.md
+---
+Drush's test suite (aka Unish) is based on [PHPUnit](http://www.phpunit.de). In order to maintain
+high quality, our tests are run on every push. See [CircleCi](https://circleci.com/gh/drush-ops/drush).
+
+## Usage
+1. git clone https://github.com/drush-ops/drush.git
+1. cd drush
+1. composer install
+1. Review the configuration settings in [tests/phpunit.xml.dist](https://github.com/drush-ops/drush/blob/10.x/tests/phpunit.xml.dist). 
+1. If customization is needed, copy phpunit.xml.dist to phpunit.xml and edit away.
+1. Run all test suites: `composer test`
+
+## Docker
+Drush's own tests may be run within provided Docker containers (see docker-compose.yml):
+
+- Start containers: `docker-compose up -d`
+- Run a test: `docker-compose exec drupal composer functional -- --filter testUserRole`
+- To change configuration, copy .env.example to .env, edit to taste, and run `docker-compose up -d` again
+- See that .env.example file for help on enabling Xdebug.
+
+## Advanced usage
+- Run only one test suite
+  - `composer unit`
+  - `composer integration`
+  - `composer functional`
+- Run only tests matching a regex: `composer functional -- --filter testUserRole`
+- Skip slow tests (usually those with network usage): `composer functional -- --exclude-group slow`
+- XML results: `composer functional -- --log-junit results.xml`
+- Ad-hoc testing with the SUT
+  - `UNISH_DIRTY=1 composer functional -- --filter testUserRole`
+  - `./drush @sut.dev status`
+
+## About the Test Suites
+- Unit tests operate on functions that take values and return results without creating side effects. No database connection is required to run these tests, and no Drupal site is set up.
+- Integration tests set up a test dependency injection container and operate by calling the Symfony Application APIs directly. A Drupal site called the System Under Test is set up and used for the tests. The SUT is set up and installed only once, and then is re-used for all tests. Integration tests therefore cannot make destructive changes to the SUT database. Also, Drupal is bootstrapped only once (always using the standard Drupal kernel, never the install or update kernel). This means that all commands run at BOOTSTRAP_FULL, and it is not possible to test loading different Drush configuration files and so on. It is not possible to test argument / option parsing. The shutdown and error handlers are not installed, so PHP deprecation warnings will be evidenced in the integration tests.
+- Functional tests operate by `exec`ing the Drush executable. All functional tests therefore run in their own separate processes. The Drupal System Under Test is set up every time it is needed by any functional test. It is therefore okay if a functional test changes the state of the SUT. The codebase is re-used, so no destructive changes should be made to the code.
+
+## Drush Test Traits
+Drush provides test traits that may be used to test your own Drush extensions. Adding the traits varies slightly depending how you package your Drush extension:
+- An extension that ships inside a contributed module. See [DevelCommandsTest](https://cgit.drupalcode.org/devel/tree/tests/src/Functional/DevelCommandsTest.php?h=8.x-2.x) for an example. Note that you also need a [drupalci.yml](https://www.drupal.org/drupalorg/docs/drupal-ci/customizing-drupalci-testing-for-projects), which performs a `composer require drush/drush`. You can copy devel's [drupalci.yml](https://cgit.drupalcode.org/devel/tree/drupalci.yml?h=8.x-2.x). Also see [SchedulerDrushTest](https://git.drupalcode.org/project/scheduler/blob/8.x-1.x/tests/src/Functional/SchedulerDrushTest.php).
+- A standalone Drush extension or one that ships inside a custom module. See [example drush extension](https://github.com/drush-ops/example-drush-extension). 
+
+Once you have included the Drush Test Traits, you will be able to write simple tests that call your extension's commands and makes assertions against the output.
+```php
+    public function testMyCommand()
+    {
+        $this->drush('my:command', ['param'], ['flag' => 'value']);
+        $this->assertOutputEquals('The parameter is "param" and the "flag" option is "value"');
+    }
+```