Merge branch '2.8' into 3.4

* 2.8:
  Improved the section about overriding bundle services
  Added a caution note about race conditions in EntityType

Author: javiereguiluz

bundles/override.rst

@@ -43,28 +43,12 @@ before the bundle one).
 Services & Configuration
 ------------------------
 
-If you want to modify service definitions of another bundle, you can use a compiler
-pass to change the class of the service or to modify method calls. In the following
-example, the implementing class for the ``original-service-id`` is changed to
-``Acme\DemoBundle\YourService``::
-
-    // src/Acme/DemoBundle/DependencyInjection/Compiler/OverrideServiceCompilerPass.php
-    namespace Acme\DemoBundle\DependencyInjection\Compiler;
-
-    use Acme\DemoBundle\YourService;
-    use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
-    use Symfony\Component\DependencyInjection\ContainerBuilder;
-
-    class OverrideServiceCompilerPass implements CompilerPassInterface
-    {
-        public function process(ContainerBuilder $container)
-        {
-            $definition = $container->getDefinition('original-service-id');
-            $definition->setClass(YourService::class);
-        }
-    }
-
-For more information on compiler passes, see :doc:`/service_container/compiler_passes`.
+If you want to modify the services created by a bundle, you can use
+:doc:`service decoration </service_container/service_decoration>`.
+
+If you want to do more advanced manipulations, like removing services created by
+other bundles, you must work with :doc:`service definitions </service_container/definitions>`
+inside a :doc:`compiler pass </service_container/compiler_passes>`.
 
 Entities & Entity Mapping
 -------------------------

reference/constraints/UniqueEntity.rst

@@ -110,6 +110,13 @@ your user table:
             }
         }
 
+.. caution::
+
+    This constraint doesn't provide any protection against `race conditions`_.
+    They may occur when another entity is persisted by an external process after
+    this validation has passed and before this entity is actually persisted in
+    the database.
+
 Options
 -------
 
@@ -284,3 +291,5 @@ If set to ``false``, only one ``null`` value is allowed - if a second entity
 also has a ``null`` value, validation would fail.
 
 .. include:: /reference/constraints/_payload-option.rst.inc
+
+.. _`race conditions`: https://en.wikipedia.org/wiki/Race_condition

service_container/compiler_passes.rst

@@ -5,10 +5,10 @@
 How to Work with Compiler Passes in Bundles
 ===========================================
 
-Compiler passes give you an opportunity to manipulate other service
-definitions that have been registered with the service container. You
-can read about how to create them in the components section
-":ref:`components-di-separate-compiler-passes`".
+Compiler passes give you an opportunity to manipulate other
+:doc:`service definitions </service_container/definitions>` that have been
+registered with the service container. You can read about how to create them in
+the components section ":ref:`components-di-separate-compiler-passes`".
 
 When using :ref:`separate compiler passes <components-di-separate-compiler-passes>`,
 you need to register them in the ``build()`` method of the bundle class (this
@@ -31,8 +31,8 @@ is not needed when implementing the ``process()`` method in the extension)::
         }
     }
 
-One of the most common use-cases of compiler passes is to work with tagged services
-(read more about tags in ":doc:`/service_container/tags`"). If you are using
+One of the most common use-cases of compiler passes is to work with
+":doc:`service tags </service_container/tags>`". If you are using
 custom tags in a bundle then by convention, tag names consist of the name of
 the bundle (lowercase, underscores as separators), followed by a dot, and
 finally the "real" name. For example, if you want to introduce some sort of