Added migration documentation for changes introduced by #99

Author: weierophinney

doc/book/migration/index.md

@@ -0,0 +1,12 @@
+# Migration
+
+While we strive to keep functionality backwards compatible between releases,
+occasionally we need to break features in order to fix critical or security
+issues. Additionally, in order to signal upcoming changes, we will introduce
+deprecation notices or add forwards-compatibility features to assist you in
+migration.
+
+The chapters in this section document these changes.
+
+- [Migrating from v2.X to v2.7](to-v2-7.md)
+- [Migrating to v3.0](to-v3-0.md)

doc/book/migration.md renamed to doc/book/migration/to-v2-7.md

@@ -1,15 +1,13 @@
-# Migration Guide
-
 ## Upgrading to 2.7
 
-### Middleware
+## Middleware
 
 zend-mvc now registers `Zend\Mvc\MiddlewareListener` as a dispatch listener at
 a priority higher than `Zend\Mvc\DispatchListener`, allowing dispatch of
 [PSR-7](http://www.php-fig.org/psr/psr-7/) middleware. Read the
-[middleware chapter](middleware.md) for details on how to use this new feature.
+[middleware chapter](../middleware.md) for details on how to use this new feature.
 
-### Application
+## Application
 
 The constructor signature of `Zend\Mvc\Application` has changed. Previously, it
 was:
@@ -43,7 +41,7 @@ signature.
 This change should only affect users who are manually instantiating the
 `Application` instance.
 
-### EventManagerAware initializers
+## EventManagerAware initializers
 
 zend-mvc provides two mechanisms for injecting event managers into
 `EventManagerAware` objects. One is the "EventManagerAwareInitializer"
@@ -80,7 +78,7 @@ This likely will not cause regressions in existing code, but may be something to
 be aware of if you were previously depending on lazy-loaded event manager
 state.
 
-### ServiceLocatorAware initializers
+## ServiceLocatorAware initializers
 
 zend-servicemanager v3.0 removes `Zend\ServiceManager\ServiceLocatorAwareInterface`.
 Since zend-mvc provides initializers around that interface, they needed updates

doc/book/migration/to-v3-0.md

@@ -0,0 +1,79 @@
+# Upgrading to 3.0 
+
+With the release of Zend Framework 2, all components current at that time,
+regardless of history, were tagged as v2 releases; in reality, it was the first
+version of a new framework, as it was a completely new architecture from Zend
+Framework 1. As such, zend-mvc 3.0 marks the second major release of the
+component.
+
+The primary goal for version 3 was to reduce the number of dependencies, and to
+split out unrelated, tangential, or extension functionality. As such, there are
+a number of changes that will impact users.
+
+## Dependency reduction
+
+In order to remove dependencies, we needed to provide alternate ways to ensure
+that default functionality, such as service registration and event listener
+attachment, could still occur.
+
+The solution to this problem was to expose each component as a module. This
+however, raised another problem: you now have to register components as modules
+in your application.
+
+To solve this new problem, we created a new component,
+[zend-component-installer](http://zendframework.github.io/zend-component-installer/).
+Install this in your application now:
+
+```bash
+$ composer require --dev zendframework/zend-component-installer
+```
+
+Once installed, the component acts as a Composer plugin, and will intercept
+packages marked as components or Zend Framework modules, and register them with
+your application configuration. Components are pushed to the top of the module
+list, while modules are pushed to the end. As a development component, it will
+not be installed in your production distributions.
+
+## Routing
+
+Routing was removed from zend-mvc, and moved to a new component,
+[zend-router](https://zendframework.github.io/zend-router/), which is now a
+dependency of zend-mvc.
+
+The changes that will impact users are:
+
+- [Query route removal](http://zendframework.github.io/zend-router/migration/v2-to-v3/#query-route-removal); 
+  this route had been deprecated since 2.3.0, and removed for the 3.0 release.
+- [Namespace changes](http://zendframework.github.io/zend-router/migration/v2-to-v3/#namespace-change);
+  with the separation to the zend-router component, all routes changed
+  namespaces from `Zend\Mvc\Router` to `Zend\Router`.
+
+Follow the links above for more details on these changes, and how to migrate
+your code.
+
+## Console tooling
+
+Console tooling, including console routes, were split off to a new component,
+[zend-mvc-console](https://zendframework.github.io/zend-mvc-console/). If you
+were using the console tooling, install zend-mvc-console:
+
+```bash
+$ composer require zendframework/zend-mvc-console
+```
+
+(Make sure you've already installed zend-component-installer before you do, to
+ensure the component is registered with your application!)
+
+zend-mvc-console exposes all of the same functionality as was in the v2 series
+of zend-mvc, but most components are in different namespaces. Please read the
+[zend-mvc-console migration guide](http://zendframework.github.io/zend-mvc-console/migration/v2-to-v3/)
+for full details of what changes you may need to make to your application to
+ensure console tooling continues to work.
+
+> ### Migrate your console tooling
+>
+> Due to the amount of integration required to support console tooling via the
+> MVC, we do not plan on supporting zend-mvc-console long-term. As such, we
+> recommend migrating your code to use standalone tools such as
+> [zf-console](https://github.com/zfcampus/zf-console) or
+> [Aura.Cli](https://github.com/auraphp/Aura.Cli).

doc/book/services.md

@@ -115,7 +115,7 @@ services configured out of the box.
   `Zend\Mvc\Service\ControllerPluginManagerFactory`. This instantiates the
   `Zend\Mvc\Controller\PluginManager` instance, passing it the service manager
   instance. It also uses the `DiAbstractServiceFactory` service, effectively
-  allowing you to fall back to DI in order to retrieve your [controller plugins](controller-plugins.md).
+  allowing you to fall back to DI in order to retrieve your [controller plugins](plugins.md).
   It registers a set of default controller plugins, and contains an
   initializer for injecting plugins with the current controller.
 

mkdocs.yml

@@ -13,7 +13,10 @@ pages:
       - 'Controller Plugins': plugins.md
       - Examples: examples.md
       - 'Dispatching PSR-7 Middleware': middleware.md
-      - 'Migration Guide': migration.md
+      - Migration:
+          - "Migration Overview": migration/index.md
+          - 'v2.X to v2.7': migration/to-v2-7.md
+          - 'v2.X to v3.0': migration/to-v3-0.md
 site_name: zend-mvc
 site_description: 'zend-mvc: MVC application provider'
 repo_url: 'https://github.com/zendframework/zend-mvc'