feature #31027 [Config] Deprecate TreeBuilder::root (gharlan)

This PR was merged into the 4.3-dev branch.

Discussion
----------

[Config] Deprecate TreeBuilder::root

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | no
| BC breaks?    | no
| Deprecations? | yes
| Tests pass?   |
| Fixed tickets | #29876
| License       | MIT
| Doc PR        | —

Alternative idea to #31015. Or is the `root` method still needed?

It would look like this:

![Screenshot 2019-04-09 01 15 04](https://user-images.githubusercontent.com/330436/55762865-fbd85900-5a64-11e9-9680-0870c85d1c09.png)

Commits
-------

ff6bc79eba Deprecate TreeBuilder::root

UPGRADE-4.3.md

@@ -20,6 +20,7 @@ Config
 ------
 
  * Deprecated using environment variables with `cannotBeEmpty()` if the value is validated with `validate()`
+ * Deprecated the `root()` method in `TreeBuilder`, pass the root node information to the constructor instead
 
 DependencyInjection
 -------------------

UPGRADE-5.0.md

@@ -25,6 +25,7 @@ Config
  * The `Processor` class has been made final
  * Removed `FileLoaderLoadException`, use `LoaderLoadException` instead.
  * Using environment variables with `cannotBeEmpty()` if the value is validated with `validate()` will throw an exception.
+ * Removed the `root()` method in `TreeBuilder`, pass the root node information to the constructor instead
 
 Console
 -------

src/Symfony/Component/Config/CHANGELOG.md

@@ -6,6 +6,7 @@ CHANGELOG
 
  * deprecated using environment variables with `cannotBeEmpty()` if the value is validated with `validate()`
  * made `Resource\*` classes final and not implement `Serializable` anymore
+ * deprecated the `root()` method in `TreeBuilder`, pass the root node information to the constructor instead
 
 4.2.0
 -----

src/Symfony/Component/Config/Definition/Builder/TreeBuilder.php

@@ -29,7 +29,8 @@ class TreeBuilder implements NodeParentInterface
         if (null === $name) {
             @trigger_error('A tree builder without a root node is deprecated since Symfony 4.2 and will not be supported anymore in 5.0.', E_USER_DEPRECATED);
         } else {
-            $this->root($name, $type, $builder);
+            $builder = $builder ?: new NodeBuilder();
+            $this->root = $builder->node($name, $type)->setParent($this);
         }
     }
 
@@ -43,9 +44,13 @@ class TreeBuilder implements NodeParentInterface
      * @return ArrayNodeDefinition|NodeDefinition The root node (as an ArrayNodeDefinition when the type is 'array')
      *
      * @throws \RuntimeException When the node type is not supported
+     *
+     * @deprecated since Symfony 4.3, pass the root name to the constructor instead
      */
     public function root($name, $type = 'array', NodeBuilder $builder = null)
     {
+        @trigger_error(sprintf('The "%s()" method called for the "%s" configuration is deprecated since Symfony 4.3, pass the root name to the constructor instead.', __METHOD__, $name), E_USER_DEPRECATED);
+
         $builder = $builder ?: new NodeBuilder();
 
         return $this->root = $builder->node($name, $type)->setParent($this);

src/Symfony/Component/Config/Tests/Definition/Builder/TreeBuilderTest.php

@@ -197,4 +197,14 @@ class TreeBuilderTest extends TestCase
     {
         new TreeBuilder();
     }
+
+    /**
+     * @group legacy
+     * @expectedDeprecation The "Symfony\Component\Config\Definition\Builder\TreeBuilder::root()" method called for the "foo" configuration is deprecated since Symfony 4.3, pass the root name to the constructor instead.
+     */
+    public function testRoot()
+    {
+        $builder = new TreeBuilder('foo');
+        $builder->root('foo');
+    }
 }