bug #8796 Upgrading the upgrade docs (weaverryan)

This PR was merged into the 4.0 branch.

Discussion
----------

Upgrading the upgrade docs

Commits
-------

431b0b9 upgrading the upgrade docs

Author: weaverryan

setup/flex.rst

@@ -124,6 +124,8 @@ Symfony application by executing the following command:
     recommended since Symfony 3.3. Use the Composer ``create-project`` command
     instead.
 
+.. _upgrade-to-flex:
+
 Upgrading Existing Applications to Flex
 ---------------------------------------
 

setup/upgrade_major.rst

@@ -1,7 +1,7 @@
 .. index::
     single: Upgrading; Major Version
 
-Upgrading a Major Version (e.g. 2.7.0 to 3.0.0)
+Upgrading a Major Version (e.g. 3.4.0 to 4.0.0)
 ===============================================
 
 Every two years, Symfony releases a new major version release (the first number
@@ -30,10 +30,10 @@ backwards incompatible changes. To accomplish this, the "old" (e.g. functions,
 classes, etc) code still works, but is marked as *deprecated*, indicating that
 it will be removed/changed in the future and that you should stop using it.
 
-When the major version is released (e.g. 3.0.0), all deprecated features and
+When the major version is released (e.g. 4.0.0), all deprecated features and
 functionality are removed. So, as long as you've updated your code to stop
 using these deprecated features in the last version before the major (e.g.
-2.8.*), you should be able to upgrade without a problem.
+3.4.*), you should be able to upgrade without a problem.
 
 To help you with this, deprecation notices are triggered whenever you end up
 using a deprecated feature. When visiting your application in the
@@ -95,7 +95,7 @@ done!
 .. sidebar:: Using the Weak Deprecations Mode
 
     Sometimes, you can't fix all deprecations (e.g. something was deprecated
-    in 2.8 and you still need to support 2.7). In these cases, you can still
+    in 3.4 and you still need to support 3.3). In these cases, you can still
     use the bridge to fix as many deprecations as possible and then switch
     to the weak test mode to make your tests pass again. You can do this by
     using the ``SYMFONY_DEPRECATIONS_HELPER`` env variable:
@@ -113,12 +113,6 @@ done!
 
     (you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=weak phpunit``).
 
-.. tip::
-
-    Some members of the Symfony Community have developed a tool called
-    `Symfony-Upgrade-Fixer`_ which automatically fixes some of the most common
-    deprecations found when upgrading from Symfony 2 to Symfony 3.
-
 .. _upgrade-major-symfony-composer:
 
 2) Update to the New Major Version via Composer
@@ -133,7 +127,7 @@ Composer by modifying your ``composer.json`` file:
         "...": "...",
 
         "require": {
-            "symfony/symfony": "3.0.*",
+            "symfony/symfony": "^4.0",
         },
         "...": "..."
     }
@@ -153,10 +147,16 @@ Next, use Composer to download new versions of the libraries:
 3) Update your Code to Work with the New Version
 ------------------------------------------------
 
-There is a good chance that you're done now! However, the next major version
-*may* also contain new BC breaks as a BC layer is not always a possibility.
-Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major version)
-included in the Symfony repository for any BC break that you need to be aware
+The next major version *may* also contain new BC breaks as a BC layer is not always
+a possibility. Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major
+version) included in the Symfony repository for any BC break that you need to be aware
 of.
 
+4) Updating to the Symfony 4 Flex Directory Structure
+-----------------------------------------------------
+
+When upgrading to Symfony 4, you will probably also want to upgrade to the new
+Symfony 4 directory structure so that you can take advantage of Symfony Flex.
+This takes some work, but is optional. For details, see :ref:`upgrade-to-flex`.
+
 .. _`Symfony-Upgrade-Fixer`: https://github.com/umpirsky/Symfony-Upgrade-Fixer

setup/upgrade_minor.rst

@@ -1,7 +1,7 @@
 .. index::
     single: Upgrading; Minor Version
 
-Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1)
+Upgrading a Minor Version (e.g. 3.3.3 to 3.4.0)
 ===============================================
 
 If you're upgrading a minor version (where the middle number changes), then
@@ -30,7 +30,7 @@ to use the new version:
         "...": "...",
 
         "require": {
-            "symfony/symfony": "2.6.*",
+            "symfony/symfony": "3.4.*",
         },
         "...": "...",
     }
@@ -55,12 +55,12 @@ to your code to get everything working. Additionally, some features you're
 using might still work, but might now be deprecated. While that's just fine,
 if you know about these deprecations, you can start to fix them over time.
 
-Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-2.7.md`_)
+Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-3.4.md`_)
 included in the Symfony directory that describes these changes. If you follow
 the instructions in the document and update your code accordingly, it should be
 safe to update in the future.
 
 These documents can also be found in the `Symfony Repository`_.
 
 .. _`Symfony Repository`: https://github.com/symfony/symfony
-.. _`UPGRADE-2.7.md`: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.7.md
+.. _`UPGRADE-3.4.md`: https://github.com/symfony/symfony/blob/3.4/UPGRADE-3.4.md

setup/upgrade_patch.rst

@@ -1,7 +1,7 @@
 .. index::
     single: Upgrading; Patch Version
 
-Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1)
+Upgrading a Patch Version (e.g. 3.3.2 to 3.3.3)
 ===============================================
 
 When a new patch version is released (only the last number changed), it is a
@@ -15,7 +15,7 @@ version is *really* easy:
 That's it! You should not encounter any backwards-compatibility breaks or
 need to change anything else in your code. That's because when you started
 your project, your ``composer.json`` included Symfony using a constraint
-like ``2.6.*``, where only the *last* version number will change when you
+like ``3.3.*``, where only the *last* version number will change when you
 update.
 
 .. tip::