From e95bf63aa8a227079c0fd1ffedf7927826db833b Mon Sep 17 00:00:00 2001
From: Javier Eguiluz <javier.eguiluz@gmail.com>
Date: Thu, 12 Jul 2018 17:09:59 +0200
Subject: [PATCH] Improved the section about overriding bundle services

---
 bundles/override.rst                  | 28 ++++++---------------------
 service_container/compiler_passes.rst | 12 ++++++------
 2 files changed, 12 insertions(+), 28 deletions(-)

diff --git a/bundles/override.rst b/bundles/override.rst
index 52950a29c3c..fb5893b76c7 100644
--- a/bundles/override.rst
+++ b/bundles/override.rst
@@ -45,28 +45,12 @@ If the controller is a service, see the next section on how to override it.
 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
 -------------------------
diff --git a/service_container/compiler_passes.rst b/service_container/compiler_passes.rst
index d93ddd3d01b..b43527c27b5 100644
--- a/service_container/compiler_passes.rst
+++ b/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