Merge branch '3.4'

* 3.4:
  Added Best Practice guideline for partials/include
  Backporting #8600
  [#8605] Updated the article a little more, using the tests/ directory.
  fix paths
  Move `schema_filter` option to the correct place
  Fix typo in "advanced ACL concepts"
  Add special Abstract prefix not usage for PHPUnit test cases

Author: weaverryan

best_practices/templates.rst

@@ -39,6 +39,15 @@ This recommendation aligns with Twig best practices, where variables and templat
 names use lowercased snake_case too (e.g. ``user_profile`` instead of ``userProfile``
 and ``edit_form.html.twig`` instead of ``EditForm.html.twig``).
 
+.. best-practice::
+
+    Use a prefixed underscore for partial templates in template names.
+
+You often want to reuse template code using the ``include`` function to avoid
+redundant code. To determine those partials easily in the filesystem you should
+prefix partials and any other template without HTML body or ``extends`` tag
+with a single underscore.
+
 Twig Extensions
 ---------------
 

contributing/code/standards.rst

@@ -190,9 +190,10 @@ Naming Conventions
 
 * Use namespaces for all classes;
 
-* Prefix abstract classes with ``Abstract``. Please note some early Symfony classes
-  do not follow this convention and have not been renamed for backward compatibility
-  reasons. However all new abstract classes must follow this naming convention;
+* Prefix all abstract classes with ``Abstract`` except PHPUnit ``*TestCase``.
+  Please note some early Symfony classes do not follow this convention and
+  have not been renamed for backward compatibility reasons. However all new
+  abstract classes must follow this naming convention;
 
 * Suffix interfaces with ``Interface``;
 

reference/configuration/doctrine.rst

@@ -22,9 +22,7 @@ Full Default Configuration
                     some_custom_type:
                         class:                Acme\HelloBundle\MyCustomType
                         commented:            true
-                # If defined, all the tables whose names match this regular expression are ignored
-                # by the schema tool (in this example, any table name starting with `wp_`)
-                #schema_filter:               '/^(?!wp_)/'
+                
 
                 connections:
                     # A collection of different named connections (e.g. default, conn2, etc)
@@ -77,6 +75,11 @@ Full Default Configuration
                         mapping_types:
                             # an array of mapping types
                             name:                 []
+                            
+                        # If defined, only the tables whose names match this regular expression are managed
+                        # by the schema tool (in this example, any table name not starting with `wp_`)
+                        #schema_filter:               '/^(?!wp_)/'
+                        
                         slaves:
 
                             # a collection of named slave connections (e.g. slave1, slave2)

testing/bootstrap.rst

@@ -6,40 +6,47 @@ running those tests. For example, if you're running a functional test and
 have introduced a new translation resource, then you will need to clear your
 cache before running those tests.
 
-To do this, first add the following file::
+To do this, first add a file that executes your bootstrap work::
 
-    // app/tests.bootstrap.php
+    // tests/bootstrap.php
     if (isset($_ENV['BOOTSTRAP_CLEAR_CACHE_ENV'])) {
+        // executes the "php bin/console cache:clear" command
         passthru(sprintf(
-            'php "%s/console" cache:clear --env=%s --no-warmup',
+            'php "%s/../bin/console" cache:clear --env=%s --no-warmup',
             __DIR__,
             $_ENV['BOOTSTRAP_CLEAR_CACHE_ENV']
         ));
     }
 
-    require __DIR__.'/autoload.php';
+    require __DIR__.'/../vendor/autoload.php';
 
-Replace the test bootstrap file ``autoload.php`` in ``phpunit.xml.dist``
-with ``tests.bootstrap.php``:
+Then, configure ``phpunit.xml.dist`` to execute this ``bootstra.php`` file
+before running the tests:
 
 .. code-block:: xml
 
     <!-- phpunit.xml.dist -->
-
-    <!-- ... -->
+    <?xml version="1.0" encoding="UTF-8"?>
     <phpunit
-        bootstrap = "tests.bootstrap.php"
+        bootstrap="tests/bootstrap.php"
     >
+        <!-- ... -->
+    </phpunit>
 
 Now, you can define in your ``phpunit.xml.dist`` file which environment you want the
 cache to be cleared:
 
 .. code-block:: xml
 
     <!-- phpunit.xml.dist -->
-    <php>
-        <env name="BOOTSTRAP_CLEAR_CACHE_ENV" value="test"/>
-    </php>
+    <?xml version="1.0" encoding="UTF-8"?>
+    <phpunit>
+        <!-- ... -->
+
+        <php>
+            <env name="BOOTSTRAP_CLEAR_CACHE_ENV" value="test" />
+        </php>
+    </phpunit>
 
 This now becomes an environment variable (i.e. ``$_ENV``) that's available
 in the custom bootstrap file (``tests.bootstrap.php``).