Merge branch '2.3' into 2.5

* 2.3:
  Putting #pull-request-format anchor link back, which we link to in our contrib notes
  Re-adding one more version
  [#4290] Re-adding version back
  Fixing bad link
  Updating library/bundle installation docs to use the new composer require (no version) functionality

Conflicts:
	components/dependency_injection/lazy_services.rst
	cookbook/bundles/installation.rst

Author: weaverryan

components/dependency_injection/lazy_services.rst

@@ -30,21 +30,19 @@ the `ProxyManager bridge`_:
 
 .. code-block:: bash
 
-    $ php composer.phar require symfony/proxy-manager-bridge:2.3.*
+    $ php composer.phar require symfony/proxy-manager-bridge:~2.3
 
 .. note::
 
     If you're using the full-stack framework, the proxy manager bridge is already
-    included but the actual proxy manager needs to be included. Therefore add
+    included but the actual proxy manager needs to be included. So, run:
 
-    .. code-block:: json
+    .. code-block:: bash
 
-        "require": {
-            "ocramius/proxy-manager": "0.5.*"
-        }
+        $ php composer.phar require ocramius/proxy-manager:~0.5
 
-    to your ``composer.json``. Afterwards compile your container and check
-    to make sure that you get a proxy for your lazy services.
+    Afterwards compile your container and check to make sure that you get
+    a proxy for your lazy services.
 
 Configuration
 -------------

contributing/documentation/overview.rst

@@ -94,6 +94,8 @@ to base your changes on. The **compare repository** should be your forked copy
 of ``symfony-docs`` and the **compare branch** should be ``improve_install_chapter``,
 which is the name of the branch you created and where you made your changes.
 
+.. _pull-request-format:
+
 **Step 8.** The last step is to prepare the **description** of the pull request.
 To ensure that your work is reviewed quickly, please add the following table
 at the beginning of your pull request description:

cookbook/bundles/best_practices.rst

@@ -219,7 +219,7 @@ following standardized instructions in your ``README.md`` file.
     following command to download the latest stable version of this bundle:
 
     ```bash
-    $ composer require <package-name> "~1"
+    $ composer require <package-name>
     ```
 
     This command requires you to have Composer installed globally, as explained
@@ -254,9 +254,6 @@ following standardized instructions in your ``README.md`` file.
     }
     ```
 
-This template assumes that your bundle is in its ``1.x`` version. If not, change
-the ``"~1"`` installation version accordingly (``"~2"``, ``"~3"``, etc.)
-
 Optionally, you can add more installation steps (*Step 3*, *Step 4*, etc.) to
 explain other required installation tasks, such as registering routes or
 dumping assets.

cookbook/bundles/installation.rst

@@ -5,69 +5,46 @@ How to Install 3rd Party Bundles
 ================================
 
 Most bundles provide their own installation instructions. However, the
-basic steps for installing a bundle are the same.
+basic steps for installing a bundle are the same:
 
-Add Composer Dependencies
--------------------------
+* `A) Add Composer Dependencies`_
+* `B) Enable the Bundle`_
+* `C) Configure the Bundle`_
 
-In Symfony, dependencies are managed with Composer. It's a good idea to learn
-some basics of Composer in `their documentation`_.
+A) Add Composer Dependencies
+----------------------------
 
-Before you can use Composer to install a bundle, you should look for a
-`Packagist`_ package of that bundle. For example, if you search for the popular
-`FOSUserBundle`_ you will find a package called `friendsofsymfony/user-bundle`_.
+Dependencies are managed with Composer, so if Composer is new to you, learn
+some basics in `their documentation`_. This has 2 steps:
 
-.. note::
-
-    Packagist is the main archive for Composer. If you are searching
-    for a bundle, the best thing you can do is check out
-    `KnpBundles`_, it is the unofficial archive of Symfony Bundles. If
-    a bundle contains a ``README`` file, it is displayed there and if it
-    has a Packagist package it shows a link to the package. It's a
-    really useful site to begin searching for bundles.
+1) Find out the Name of the Bundle on Packagist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Now that you have the package name, you should determine the version
-you want to use. Usually different versions of a bundle correspond to
-a particular version of Symfony. This information should be in the ``README``
-file. If it isn't, you can use the version you want. If you choose an incompatible
-version, Composer will throw dependency errors when you try to install. If
-this happens, you can try a different version.
+The README for a bundle (e.g. `FOSUserBundle`_) usually tells you its name
+(e.g. ``friendsofsymfony/user-bundle``). If it doesn't, you can search for
+the library on the `Packagist.org`_ site.
 
-Now you can add the bundle to your ``composer.json`` file and update the
-dependencies. You can do this manually:
-
-1. **Add it to the ``composer.json`` file:**
+.. note::
 
-   .. code-block:: json
+    Looking for bundles? Try searching at `KnpBundles.com`_: the unofficial
+    archive of Symfony Bundles.
 
-       {
-           ...,
-           "require": {
-               ...,
-               "friendsofsymfony/user-bundle": "2.0.*@dev"
-           }
-       }
+2) Install the Bundle via Composer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-2. **Update the dependency:**
+Now that you know the package name, you can install it via Composer:
 
    .. code-block:: bash
 
-       $ php composer.phar update friendsofsymfony/user-bundle
-
-   or update all dependencies
-
-   .. code-block:: bash
+       $ php composer.phar require friendsofsymfony/user-bundle
 
-       $ php composer.phar update
+This will choose the best version for your project, add it to ``composer.json``
+and download the library into the ``vendor/`` directory. If you need a specific
+version, add a ``:`` and the version right after the library name (see
+`composer require`_).
 
-Or you can do this in one command:
-
-.. code-block:: bash
-
-    $ php composer.phar require friendsofsymfony/user-bundle:2.0.*@dev
-
-Enable the Bundle
------------------
+B) Enable the Bundle
+--------------------
 
 At this point, the bundle is installed in your Symfony project (in
 ``vendor/friendsofsymfony/``) and the autoloader recognizes its classes.
@@ -91,13 +68,13 @@ The only thing you need to do now is register the bundle in ``AppKernel``::
         }
     }
 
-Configure the Bundle
---------------------
+C) Configure the Bundle
+-----------------------
 
-Usually a bundle requires some configuration to be added to app's
-``app/config/config.yml`` file. The bundle's documentation will likely
-describe that configuration. But you can also get a reference of the
-bundle's config via the ``config:dump-reference`` command.
+It's pretty common for a bundle to need some additional setup or configuration
+in ``app/config/config.yml``. The bundle's documentation will tell you about
+the configuration, but you can also get a reference of the bundle's config
+via the ``config:dump-reference`` command.
 
 For instance, in order to look the reference of the ``assetic`` config you
 can use this:
@@ -132,10 +109,10 @@ Other Setup
 -----------
 
 At this point, check the ``README`` file of your brand new bundle to see
-what to do next.
+what to do next. Have fun!
 
 .. _their documentation: http://getcomposer.org/doc/00-intro.md
-.. _Packagist:           https://packagist.org
+.. _Packagist.org:       https://packagist.org
 .. _FOSUserBundle:       https://github.com/FriendsOfSymfony/FOSUserBundle
-.. _`friendsofsymfony/user-bundle`: https://packagist.org/packages/friendsofsymfony/user-bundle
-.. _KnpBundles:          http://knpbundles.com/
+.. _KnpBundles.com:      http://knpbundles.com/
+.. _`composer require`:  https://getcomposer.org/doc/03-cli.md#require

cookbook/workflow/_vendor_deps.rst.inc

@@ -24,29 +24,12 @@ To upgrade your libraries to new versions, run ``php composer.phar update``.
 
 .. tip::
 
-    If you want to add a new package to your application, modify the ``composer.json``
-    file:
-
-    .. code-block:: json
-
-        {
-            "require": {
-                ...
-                "doctrine/doctrine-fixtures-bundle": "@dev"
-            }
-        }
-
-    and then execute the ``update`` command for this specific package, i.e.:
-
-    .. code-block:: bash
-
-        $ php composer.phar update doctrine/doctrine-fixtures-bundle
-
-    You can also combine both steps into a single command:
+    If you want to add a new package to your application, run the composer
+    ``require`` command:
 
     .. code-block:: bash
 
-        $ php composer.phar require doctrine/doctrine-fixtures-bundle:@dev
+        $ php composer.phar require doctrine/doctrine-fixtures-bundle
 
 To learn more about Composer, see `GetComposer.org`_: