Merge branch '3.4' into 4.3

* 3.4:
  Add in the DOW crawler documentation code sample to show how to tick checkboxes
  Adds the most basic informations about loaders
  [symfony#12075] fix some casing
  [Contributing] Add more information on deprecations

Author: OskarStark

components/config/resources.rst

@@ -10,6 +10,8 @@ Loading Resources
     :phpfunction:`parse_ini_file` function. Therefore, you can only set
     parameters to string values. To set parameters to other data types
     (e.g. boolean, integer, etc), the other loaders are recommended.
+    
+Loaders populate the application's configuration from different sources like YAML files. The Config component defines the interface for such loaders. The :doc:`Dependency Injection </components/dependency_injection>` and :doc:`Routing </components/routing>` components come with specialized loaders for different file formats.
 
 Locating Resources
 ------------------

components/dom_crawler.rst

@@ -511,6 +511,9 @@ To work with multi-dimensional fields::
         <input name="multi[]"/>
         <input name="multi[]"/>
         <input name="multi[dimensional]"/>
+        <input name="multi[dimensional][]" value="1"/>
+        <input name="multi[dimensional][]" value="2"/>
+        <input name="multi[dimensional][]" value="3"/>
     </form>
 
 Pass an array of values::
@@ -524,6 +527,11 @@ Pass an array of values::
         'dimensional' => 'an other value',
     ]]);
 
+    // tick multiple checkboxes at once
+    $form->setValues(['multi' => [
+        'dimensional' => [1, 3] // it uses the input value to determine which checkbox to tick
+    ]]);
+
 This is great, but it gets better! The ``Form`` object allows you to interact
 with your form like a browser, selecting radio values, ticking checkboxes,
 and uploading files::

contributing/code/conventions.rst

@@ -79,30 +79,46 @@ must be used instead (where ``XXX`` is the name of the related thing):
 
 .. _contributing-code-conventions-deprecations:
 
-Deprecations
-------------
+Deprecating Code
+----------------
 
 From time to time, some classes and/or methods are deprecated in the
 framework; that happens when a feature implementation cannot be changed
 because of backward compatibility issues, but we still want to propose a
 "better" alternative. In that case, the old implementation can be **deprecated**.
 
+Deprecations must only be introduced on the next minor version of the impacted
+component (or bundle, or bridge, or contract).
+They can exceptionally be introduced on previous supported versions if they are critical.
+
+A new class (or interface, or trait) cannot be introduced as deprecated, or
+contain deprecated methods.
+
+A new method cannot be introduced as deprecated.
+
 A feature is marked as deprecated by adding a ``@deprecated`` phpdoc to
 relevant classes, methods, properties, ...::
 
     /**
-     * @deprecated since vendor-name/package-name 2.8, to be removed in 3.0. Use XXX instead.
+     * @deprecated since Symfony 2.8.
+     */
+
+The deprecation message must indicate the version in which the feature was deprecated,
+and whenever possible, how it was replaced::
+
+    /**
+     * @deprecated since Symfony 2.8, use Replacement instead.
      */
 
-The deprecation message should indicate the version when the class/method was
-deprecated, the version when it will be removed, and whenever possible, how
-the feature was replaced.
+When the replacement is in another namespace than the deprecated class, its FQCN must be used::
+
+    /**
+     * @deprecated since Symfony 2.8, use A\B\Replacement instead.
+     */
 
-A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with
-the migration starting one or two minor versions before the version where the
-feature will be removed (depending on the criticality of the removal)::
+A PHP ``E_USER_DEPRECATED`` error must also be triggered to help people with the migration::
 
-    @trigger_error('XXX() is deprecated since vendor-name/package-name 2.8 and will be removed in 3.0. Use XXX instead.', E_USER_DEPRECATED);
+    @trigger_error(sprintf('The "%s" class is deprecated since Symfony 2.8, use "%s" instead.', Deprecated::class, Replacement::class), E_USER_DEPRECATED);
 
 Without the `@-silencing operator`_, users would need to opt-out from deprecation
 notices. Silencing swaps this behavior and allows users to opt-in when they are
@@ -113,19 +129,58 @@ the Web Debug Toolbar or by the PHPUnit bridge).
 
 When deprecating a whole class the ``trigger_error()`` call should be placed
 between the namespace and the use declarations, like in this example from
-`ArrayParserCache`_::
+`ServiceRouterLoader`_::
 
-    namespace Symfony\Component\ExpressionLanguage\ParserCache;
+    namespace Symfony\Component\Routing\Loader\DependencyInjection;
 
-    @trigger_error('The '.__NAMESPACE__.'\ArrayParserCache class is deprecated since version 3.2 and will be removed in 4.0. Use the Symfony\Component\Cache\Adapter\ArrayAdapter class instead.', E_USER_DEPRECATED);
+    use Symfony\Component\Routing\Loader\ContainerLoader;
 
-    use Symfony\Component\ExpressionLanguage\ParsedExpression;
+    @trigger_error(sprintf('The "%s" class is deprecated since Symfony 4.4, use "%s" instead.', ServiceRouterLoader::class, ContainerLoader::class), E_USER_DEPRECATED);
 
     /**
-     * @author Adrien Brault <[email protected]>
-     *
-     * @deprecated since Symfony 3.2, to be removed in 4.0. Use the Symfony\Component\Cache\Adapter\ArrayAdapter class instead.
+     * @deprecated since Symfony 4.4, use Symfony\Component\Routing\Loader\ContainerLoader instead.
      */
-    class ArrayParserCache implements ParserCacheInterface
+    class ServiceRouterLoader extends ObjectRouteLoader
+
+.. _`ServiceRouterLoader`: https://github.com/symfony/symfony/blob/4.4/src/Symfony/Component/Routing/Loader/DependencyInjection/ServiceRouterLoader.php
+
+The deprecation must be added to the ``CHANGELOG.md`` file of the impacted component::
+
+    4.4.0
+    -----
+
+    * Deprecated the `Deprecated` class, use `Replacement` instead.
+
+It must also be added to the ``UPGRADE.md`` file of the targeted minor version
+(``UPGRADE-4.4.md`` in our example)::
+
+    DependencyInjection
+    -------------------
+
+    * Deprecated the `Deprecated` class, use `Replacement` instead.
+
+Finally, its consequences must be added to the ``UPGRADE.md`` file of the next major version
+(``UPGRADE-5.0.md`` in our example)::
+
+    DependencyInjection
+    -------------------
+
+    * Removed the `Deprecated` class, use `Replacement` instead.
+
+All these tasks are mandatory and must be done in the same pull request.
+
+Removing Deprecated Code
+------------------------
+
+Removing deprecated code can only be done once every 2 years, on the next major version of the
+impacted component (``master`` branch).
+
+When removing deprecated code, the consequences of the deprecation must be added to the ``CHANGELOG.md`` file
+of the impacted component::
+
+    5.0.0
+    -----
+
+    * Removed the `Deprecated` class, use `Replacement` instead.
 
-.. _`ArrayParserCache`: https://github.com/symfony/symfony/blob/3.2/src/Symfony/Component/ExpressionLanguage/ParserCache/ArrayParserCache.php
+This task is mandatory and must be done in the same pull request.