added upgrade instructions

Tobion · Tobion · commit 51223c05fff2 · 2012-11-27T20:03:51.000+01:00
diff --git a/UPGRADE-2.2.md b/UPGRADE-2.2.md
@@ -36,6 +36,42 @@
 
   * The PasswordType is now not trimmed by default.
 
+### Routing
+
+ * RouteCollection does not behave like a tree structure anymore but as a flat
+   array of Routes. So when using PHP to build the RouteCollection, you must
+   make sure to add routes to the sub-collection before adding it to the parent
+   collection (this is not relevant when using YAML or XML for Route definitions).
+
+   Before:
+
+   ```
+   $rootCollection = new RouteCollection();
+   $subCollection = new RouteCollection();
+   $rootCollection->addCollection($subCollection);
+   $subCollection->add('foo', new Route('/foo'));
+   ```
+
+   After:
+
+   ```
+   $rootCollection = new RouteCollection();
+   $subCollection = new RouteCollection();
+   $subCollection->add('foo', new Route('/foo'));
+   $rootCollection->addCollection($subCollection);
+   ```
+
+   Also one must call `addCollection` from the bottom to the top hierarchy.
+   So the correct sequence is the following (and not the reverse):
+
+   ```
+   $childCollection->->addCollection($grandchildCollection);
+   $rootCollection->addCollection($childCollection);
+   ```
+
+ * The methods `RouteCollection::getParent()` and `RouteCollection::getRoot()`
+   have been deprecated and will be removed in Symfony 2.3.
+
 ### Validator
 
  * Interfaces were created for created for the classes `ConstraintViolation`,
diff --git a/src/Symfony/Component/Routing/CHANGELOG.md b/src/Symfony/Component/Routing/CHANGELOG.md
@@ -4,6 +4,39 @@ CHANGELOG
 2.2.0
 -----
 
+ * [BC BREAK] RouteCollection does not behave like a tree structure anymore but as
+   a flat array of Routes. So when using PHP to build the RouteCollection, you must
+   make sure to add routes to the sub-collection before adding it to the parent
+   collection (this is not relevant when using YAML or XML for Route definitions).
+
+   Before:
+
+   ```
+   $rootCollection = new RouteCollection();
+   $subCollection = new RouteCollection();
+   $rootCollection->addCollection($subCollection);
+   $subCollection->add('foo', new Route('/foo'));
+   ```
+
+   After:
+
+   ```
+   $rootCollection = new RouteCollection();
+   $subCollection = new RouteCollection();
+   $subCollection->add('foo', new Route('/foo'));
+   $rootCollection->addCollection($subCollection);
+   ```
+
+   Also one must call `addCollection` from the bottom to the top hierarchy.
+   So the correct sequence is the following (and not the reverse):
+
+   ```
+   $childCollection->->addCollection($grandchildCollection);
+   $rootCollection->addCollection($childCollection);
+   ```
+
+ * The methods `RouteCollection::getParent()` and `RouteCollection::getRoot()`
+   have been deprecated and will be removed in Symfony 2.3.
  * added support for the method default argument values when defining a @Route
  * Adjacent placeholders without separator work now, e.g. `/{x}{y}{z}.{_format}`.
  * Characters that function as separator between placeholders are now whitelisted
