Merge branch '3.0' into 3.1

Author: wouterj

book/validation.rst

@@ -511,9 +511,11 @@ For information on translating the constraint messages, see
 Constraint Targets
 ------------------
 
-Constraints can be applied to a class property (e.g. ``name``) or a public
-getter method (e.g. ``getFullName``). The first is the most common and easy
-to use, but the second allows you to specify more complex validation rules.
+Constraints can be applied to a class property (e.g. ``name``), a public
+getter method (e.g. ``getFullName``) or an entire class. Property constraints
+are the most common and easy to use. Getter constraints allow you to specify
+more complex validation rules. Finally, class constraints are intended
+for scenarios where you want to validate a class as a whole.
 
 .. index::
    single: Validation; Property constraints

components/form/introduction.rst

@@ -118,7 +118,7 @@ The following snippet adds CSRF protection to the form factory::
 
     use Symfony\Component\Form\Forms;
     use Symfony\Component\HttpFoundation\Session\Session;
-    use Symfony\Component\Security\Extension\Csrf\CsrfExtension;
+    use Symfony\Component\Form\Extension\Csrf\CsrfExtension;
     use Symfony\Component\Security\Csrf\TokenStorage\SessionTokenStorage;
     use Symfony\Component\Security\Csrf\TokenGenerator\UriSafeTokenGenerator;
     use Symfony\Component\Security\Csrf\CsrfTokenManager;

components/serializer.rst

@@ -169,7 +169,7 @@ The serializer can also be used to update an existing object::
     EOF;
 
     $serializer->deserialize($data, 'Acme\Person', 'xml', array('object_to_populate' => $person));
-    // $obj2 = Acme\Person(name: 'foo', age: '69', sportsman: true)
+    // $person = Acme\Person(name: 'foo', age: '69', sportsman: true)
 
 This is a common need when working with an ORM.
 

contributing/code/index.rst

@@ -6,6 +6,7 @@ Contributing Code
 
     bugs
     patches
+    maintenance
     core_team
     security
     tests

contributing/code/maintenance.rst

@@ -0,0 +1,80 @@
+Maintenance
+===========
+
+During the lifetime of a minor version, new releases (patch versions) are
+published on a monthly basis. This document describes the boundaries of
+acceptable changes.
+
+**Bug fixes** are accepted under the following conditions:
+
+* The change does not break valid unit tests;
+* New unit tests cover the bug fix;
+* The current buggy behavior is not widely used as a "feature".
+
+.. note::
+
+    When documentation (or phpdoc) is not in sync with the code, code behavior
+    should always be considered as being the correct one.
+
+Besides bug fixes, other minor changes can be accepted in a patch version:
+
+* **Performance improvement**: Performance improvement should only be accepted
+  if the changes are local (located in one class) and only for algorithmic
+  issues (any such patches must come with numbers that show a significant
+  improvement on real-world code);
+
+* **Newer versions of PHP/HHVM**: Fixes that add support for newer versions of
+  PHP or HHVM are acceptable if they don't break the unit test suite;
+
+* **Newer versions of popular OSes**: Fixes that add support for newer versions
+  of popular OSes (Linux, MacOS and Windows) are acceptable if they don't break
+  the unit test suite;
+
+* **Translations**: Translation updates and additions are accepted;
+
+* **External data**: Updates for external data included in Symfony can be
+  updated (like ICU for instance);
+
+* **Version updates for Composer dependencies**: Changing the minimal version
+  of a dependency is possible, bumping to a major one or increasing PHP
+  minimal version is not;
+
+* **Coding standard and refactoring**: Coding standard fixes or code
+  refactoring are not recommended but can be accepted for consistency with the
+  existing code base, if they are not too invasive, and if merging them on
+  master would not lead to complex branch merging;
+
+* **Tests**: Tests that increase the code coverage can be added.
+
+Anything not explicitly listed above should be done on the next minor or major
+version instead (aka the *master* branch). For instance, the following changes
+are never accepted in a patch version:
+
+* **New features**;
+
+* **Backward compatibility breaks**: Note that backward compatibility breaks
+  can be done when fixing a security issue if it would not be possible to fix
+  it otherwise;
+
+* **Support for external platforms**: Adding support for new platforms (like
+  Google App Engine) cannot be done in patch versions;
+
+* **Exception messages**: Exception messages must not be changed as some
+  automated systems might rely on them (even if this is not recommended);
+
+* **Adding new Composer dependencies**;
+
+* **Support for newer major versions of Composer dependencies**: Taking into
+  account support for newer versions of an existing dependency is not
+  acceptable.
+
+* **Web design**: Changing the web design of built-in pages like exceptions,
+  the toolbar or the profiler is not allowed.
+
+.. note::
+
+    This policy is designed to enable a continuous upgrade path that allows one
+    to move forward with newest Symfony versions in the safest way. One should
+    be able to move PHP versions, OS or Symfony versions almost independently.
+    That's the reason why supporting the latest PHP versions or OS features is
+    considered as bug fixes.

contributing/code/patches.rst

@@ -113,10 +113,12 @@ Choose the right Branch
 Before working on a patch, you must determine on which branch you need to
 work:
 
-* ``2.3``, if you are fixing a bug for an existing feature (you may have
-  to choose a higher branch if the feature you are fixing was introduced
-  in a later version);
-* ``master``, if you are adding a new feature.
+* ``2.3``, if you are fixing a bug for an existing feature or want to make a
+  change that falls into the :doc:`list of acceptable changes in patch versions
+  </contributing/code/maintenance>` (you may have to choose a higher branch if
+  the feature you are fixing was introduced in a later version);
+
+ * ``master``, if you are adding a new feature.
 
 .. note::
 

contributing/community/releases.rst

@@ -48,6 +48,11 @@ type of the release. This maintenance is divided into:
   be fixed. The end of this period is referenced as being the *end of life* of
   a release.
 
+.. note::
+
+    The :doc:`maintenance document </contributing/code/maintenance>` describes
+    the boundaries of acceptable changes during maintenance.
+
 Symfony Versions
 ----------------
 

contributing/map.rst.inc

@@ -3,6 +3,7 @@
   * :doc:`Bugs </contributing/code/bugs>`
   * :doc:`Patches </contributing/code/patches>`
   * :doc:`Reviewing Issues and Patches </contributing/community/reviews>`
+  * :doc:`Maintenance </contributing/code/maintenance>`
   * :doc:`The Core Team </contributing/code/core_team>`
   * :doc:`Security </contributing/code/security>`
   * :doc:`Tests </contributing/code/tests>`

cookbook/form/form_collections.rst

@@ -297,7 +297,7 @@ new "tag" forms. To render it, make the following change to your template:
 
     .. code-block:: html+twig
 
-        <ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e }}">
+        <ul class="tags" data-prototype="{{ form_widget(form.tags.vars.prototype)|e('html_attr') }}">
             ...
         </ul>
 

cookbook/index.rst

@@ -22,13 +22,13 @@ The Cookbook
     install/index
     logging/index
     profiler/index
+    psr7
     request/index
     routing/index
     security/index
     serializer
     service_container/index
     session/index
-    psr7
     templating/index
     testing/index
     upgrade/index

reference/forms/types/datetime.rst

@@ -82,14 +82,18 @@ If your widget option is set to ``choice``, then this field will be represented
 as a series of ``select`` boxes. When the placeholder value is a string,
 it will be used as the **blank value** of all select boxes::
 
-    $builder->add('startDateTime', 'datetime', array(
+    use Symfony\Component\Form\Extension\Core\Type\DateTimeType;
+    
+    $builder->add('startDateTime', DateTimeType::class, array(
         'placeholder' => 'Select a value',
     ));
 
 Alternatively, you can use an array that configures different placeholder
 values for the year, month, day, hour, minute and second fields::
 
-    $builder->add('startDateTime', 'datetime', array(
+    use Symfony\Component\Form\Extension\Core\Type\DateTimeType;
+    
+    $builder->add('startDateTime', DateTimeType::class, array(
         'placeholder' => array(
             'year' => 'Year', 'month' => 'Month', 'day' => 'Day',
             'hour' => 'Hour', 'minute' => 'Minute', 'second' => 'Second',