Merge branch '3.4' into 4.0

* 3.4:
  Added a short section about registering commands
  Explain which branch to select for Pull Requests
  Missing the obvious <?php
  Update email field length in annotation
  Removed a duplicated content
  Clarify Symfony Console option conventions
  Clarify how to use short options with values.
  Use the long array syntax
  Fixes deprecated ProcessBuilder usage

Author: javiereguiluz

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,9 @@
+<!--
+
+If your pull request fixes a BUG, use the oldest maintained branch that contains
+the bug (see https://symfony.com/roadmap for the list of maintained branches).
+
+If your pull request documents a NEW FEATURE, use the same Symfony branch where
+the feature was introduced (and `master` for features of unreleased versions).
+
+-->

components/console/helpers/processhelper.rst

@@ -14,7 +14,7 @@ a very verbose verbosity (e.g. -vv)::
     use Symfony\Component\Process\ProcessBuilder;
 
     $helper = $this->getHelper('process');
-    $process = ProcessBuilder::create(array('figlet', 'Symfony'))->getProcess();
+    $process = new Process(array('figlet', 'Symfony'));
 
     $helper->run($output, $process);
 
@@ -55,7 +55,7 @@ There are three ways to use the process helper:
     use Symfony\Component\Process\ProcessBuilder;
 
     // ...
-    $process = ProcessBuilder::create(array('figlet', 'Symfony'))->getProcess();
+    $process = new Process(array('figlet', 'Symfony'));
 
     $helper->run($output, $process);
 

console.rst

@@ -69,25 +69,23 @@ method. Then you can optionally define a help message and the
         ;
     }
 
+Registering the Command
+-----------------------
+
+Symfony commands must be registered as services and :doc:`tagged </service_container/tags>`
+with the ``console.command`` tag. If you're using the
+:ref:`default services.yaml configuration <service-container-services-load-example>`,
+this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
+
 Executing the Command
 ---------------------
 
-You can now execute this command in the terminal:
+After configuring and registering the command, you can execute it in the terminal:
 
 .. code-block:: terminal
 
     $ php bin/console app:create-user
 
-.. note::
-
-    The command class must be registered as a service with the ``console.command`` tag.
-
-    If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
-    this is already done for you, thanks to :ref:`autoconfiguration <services-autoconfigure>`.
-
-    Otherwise, you can manually register your command as a service by configuring the service
-    and :doc:`tagging it </service_container/tags>` with ``console.command``.
-
 As you might expect, this command will do nothing as you didn't write any logic
 yet. Add your own logic inside the ``execute()`` method, which has access to the
 input stream (e.g. options and arguments) and the output stream (to write

console/input.rst

@@ -174,6 +174,11 @@ flag:
                 1
             );
 
+Note that to comply with the `docopt standard`_, long options can specify their
+values after a white space or an ``=`` sign (e.g. ``--iterations 5`` or
+``--iterations=5``), but short options can only use white spaces or no
+separation at all (e.g. ``-i 5`` or ``-i5``).
+
 There are four option variants you can use:
 
 ``InputOption::VALUE_IS_ARRAY``
@@ -184,8 +189,8 @@ There are four option variants you can use:
     behavior of options;
 
 ``InputOption::VALUE_REQUIRED``
-    This value is required (e.g. ``--iterations=5``), the option itself is
-    still optional;
+    This value is required (e.g. ``--iterations=5`` or ``-i5``), the option
+    itself is still optional;
 
 ``InputOption::VALUE_OPTIONAL``
     This option may or may not have a value (e.g. ``--yell`` or
@@ -211,3 +216,14 @@ You can combine ``VALUE_IS_ARRAY`` with ``VALUE_REQUIRED`` or
     when the option was used without a value (``command --language``) or when
     it wasn't used at all (``command``). In both cases, the value retrieved for
     the option will be ``null``.
+
+.. caution::
+
+    While it is possible to separate an option from its value with a white space,
+    using this form leads to an ambiguity should the option appear before the
+    command name. For example, ``php bin/console --iterations 5 app:greet Fabien``
+    is ambiguous; Symfony would interpret ``5`` as the command name. To avoid
+    this situation, always place options after the command name, or avoid using
+    a space to separate the option name from its value.
+
+.. _`docopt standard`: http://docopt.org/

page_creation.rst

@@ -43,6 +43,7 @@ Suppose you want to create a page - ``/lucky/number`` - that generates a lucky (
 random) number and prints it. To do that, create a "Controller class" and a
 "controller" method inside of it::
 
+    <?php
     // src/Controller/LuckyController.php
     namespace App\Controller;
 
@@ -281,7 +282,7 @@ project:
 
 ``src/``
     All your PHP code lives here.
-    
+
 ``templates/``
     All your Twig templates live here.
 

security/entity_provider.rst

@@ -67,7 +67,7 @@ with the following fields: ``id``, ``username``, ``password``,
         private $password;
 
         /**
-         * @ORM\Column(type="string", length=60, unique=true)
+         * @ORM\Column(type="string", length=254, unique=true)
          */
         private $email;