From 783b1040393f45721c150879d90f2f3c6e10b220 Mon Sep 17 00:00:00 2001
From: Ingo Schommer <me@chillu.com>
Date: Tue, 18 Dec 2018 16:19:36 +1300
Subject: [PATCH] DOC Clarify testing cache behaviour changes in 4.3

---
 .../02_Developer_Guides/06_Testing/index.md   | 10 ++++++++
 docs/en/04_Changelogs/4.3.0.md                | 23 +++++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/docs/en/02_Developer_Guides/06_Testing/index.md b/docs/en/02_Developer_Guides/06_Testing/index.md
index e00266f07..c2bdb461d 100644
--- a/docs/en/02_Developer_Guides/06_Testing/index.md
+++ b/docs/en/02_Developer_Guides/06_Testing/index.md
@@ -38,6 +38,16 @@ Check the PHPUnit manual for all available [command line arguments](http://www.p
 On Linux or OSX, you can avoid typing the full path on every invocation by adding `vendor/bin` 
 to your `$PATH` definition in the shell profile (usually `~/.profile`): `PATH=./vendor/bin:$PATH`
 
+## Caching
+
+Just like on web requests, SilverStripe caches metadata about the execution context.
+This cache can get stale, e.g. when you change YAML configuration or add certain types of PHP code.
+In order to flush the cache, use the `flush=1` CLI parameter:
+
+```
+vendor/bin/phpunit vendor/silverstripe/framework/tests '' flush=1
+```
+
 ## Generating a Coverage Report
 
 PHPUnit can generate a code coverage report ([docs](http://www.phpunit.de/manual/current/en/code-coverage-analysis.html))
diff --git a/docs/en/04_Changelogs/4.3.0.md b/docs/en/04_Changelogs/4.3.0.md
index 9ab7760ee..ed6f321da 100644
--- a/docs/en/04_Changelogs/4.3.0.md
+++ b/docs/en/04_Changelogs/4.3.0.md
@@ -8,6 +8,7 @@
  - New React-based search UI for the CMS, Asset-Admin, GridFields and ModelAdmins.
  - A new `GridFieldLazyLoader` component can be added to `GridField`. This will delay the fetching of data until the user access the container Tab of the GridField.
  - `SilverStripe\VersionedAdmin\Controllers\CMSPageHistoryViewerController` is now the default CMS history controller and `SilverStripe\CMS\Controllers\CMSPageHistoryController` has been deprecated.
+ - PHPUnit tests no longer auto-flush, requiring manual flush parameters when changing YAML config or certain PHP code
 
 ## Upgrading {#upgrading}
 
@@ -69,6 +70,28 @@ SilverStripe\Core\Injector\Injector:
 
 [Implementing a _Factory_ with the Injector](/developer_guides/extending/injector/#factories)
 
+### PHPUnit tests no longer auto-flush
+
+SilverStripe caches certain metadata in manifests, for example YAML configuration
+and certain PHP class structures (e.g. `ClassInfo::implementorsOf()`).
+This is also the case for CLI executions such as PHPUnit.
+
+Starting with SilverStripe 4.0, PHPUnit executions flushed the cache automatically.
+While this meant less work for developers in manually flushing caches,
+it significantly increased the time to run each test (from sub-second to multi-second).
+In order to allow for efficient test execution and Test Driven Development (TDD),
+we have decided to treat this as a performance regression. 
+
+In order to flush manifests on test execution, please use the following command
+(note the empty quoted string):
+
+```
+vendor/bin/phpunit vendor/silverstripe/framework/tests '' flush=1
+```
+
+See our [testing guide](https://docs.silverstripe.org/en/4/developer_guides/testing/)
+for more details.
+
 <!--- Changes below this line will be automatically regenerated -->
 
 ## Change Log