symfony
diff --git a/‎configuration/override_dir_structure.rst
Lines changed: 1 addition & 1 deletion b/‎configuration/override_dir_structure.rst
Lines changed: 1 addition & 1 deletion
diff --git a/‎console/usage.rst
Lines changed: 9 additions & 12 deletions b/‎console/usage.rst
Lines changed: 9 additions & 12 deletions
diff --git a/‎deployment.rst
Lines changed: 3 additions & 2 deletions b/‎deployment.rst
Lines changed: 3 additions & 2 deletions
diff --git a/‎reference/dic_tags.rst
Lines changed: 6 additions & 0 deletions b/‎reference/dic_tags.rst
Lines changed: 6 additions & 0 deletions
@@ -168,7 +168,7 @@ You also need to change the ``extra.symfony-web-dir`` option in the
 
     .. code-block:: terminal
 
-        $ php bin/console cache:clear --env=prod
+        $ php bin/console cache:clear --no-warmup --env=prod
         $ php bin/console assetic:dump --env=prod --no-debug
 
 Override the ``vendor`` Directory
 
@@ -8,22 +8,19 @@ The :doc:`/components/console/usage` page of the components documentation looks
 at the global console options. When you use the console as part of the full-stack
 framework, some additional global options are available as well.
 
-By default, console commands run in the ``dev`` environment and you may want
-to change this for some commands. For example, you may want to run some commands
-in the ``prod`` environment for performance reasons. Also, the result of some commands
-will be different depending on the environment. For example, the ``cache:clear``
-command will clear and warm the cache for the specified environment only. To
-clear and warm the ``prod`` cache you need to run:
+By default, console commands run in the ``dev`` environment and you may want to
+change this for some commands. For example, you may want to run some commands in
+the ``prod`` environment for performance reasons. Also, the result of some
+commands will be different depending on the environment. For example, the
+``cache:clear`` command will clear the cache for the specified environment only.
+To clear the ``prod`` cache you need to run:
 
 .. code-block:: terminal
 
-    $ php bin/console cache:clear --env=prod
+    $ php bin/console cache:clear --no-warmup --env=prod
 
-or the equivalent:
-
-.. code-block:: terminal
-
-    $ php bin/console cache:clear -e prod
+    # this is equivalent:
+    $ php bin/console cache:clear --no-warmup -e prod
 
 In addition to changing the environment, you can also choose to disable debug mode.
 This can be useful where you want to run commands in the ``dev`` environment
 
@@ -153,11 +153,12 @@ as you normally do:
 D) Clear your Symfony Cache
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Make sure you clear (and warm-up) your Symfony cache:
+Make sure you clear and warm-up your Symfony cache:
 
 .. code-block:: terminal
 
-    $ php bin/console cache:clear --env=prod --no-debug
+    $ php bin/console cache:clear --env=prod --no-debug --no-warmup
+    $ php bin/console cache:warmup --env=prod
 
 E) Dump your Assetic Assets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -504,6 +504,12 @@ process
 Cache warming occurs whenever you run the ``cache:warmup`` or ``cache:clear``
 command (unless you pass ``--no-warmup`` to ``cache:clear``). It is also run
 when handling the request, if it wasn't done by one of the commands yet.
+
+.. versionadded:: 3.3
+    Starting from Symfony 3.3, the warm-up part of the ``cache:clear`` command
+    is deprecated. You must always pass the ``--no-warmup`` option to
+    ``cache:clear`` and use ``cache:warmup`` instead to warm-up the cache.
+
 The purpose is to initialize any cache that will be needed by the application
 and prevent the first user from any significant "cache hit" where the cache
 is generated dynamically.