Merge branch '3.4' into 4.2

* 3.4:
  Added a note about PHP extension and Symfony Form types extension
  Update choice_label docs to match given examples
  Improved the explanation of the block_name form option
  [Diversity] Add Voting Logic Examples

Author: javiereguiluz

contributing/diversity/governance.rst

@@ -72,6 +72,23 @@ For an actionable item to pass, approval from greater than 50% of the voting
 guidance team members is required. Use or management of finances/donations
 require at least a two-thirds majority to pass.
 
+For transparency and ease-of-understanding, this means only the following
+combinations of votes will result in an actionable item passing:
+
++-----+---------+---------+
+| For | Against | Abstain |
++=====+=========+=========+
+| 5   | 0       | 0       |
++-----+---------+---------+
+| 4   | 1       | 0       |
++-----+---------+---------+
+| 3   | 2       | 0       |
++-----+---------+---------+
+| 4   | 0       | 1       |
++-----+---------+---------+
+| 3   | 1       | 1       |
++-----+---------+---------+
+
 Guidance Principles
 -------------------
 

form/create_custom_field_type.rst

@@ -16,8 +16,11 @@ Defining the Field Type
 In order to create the custom field type, first you have to create the class
 representing the field. In this situation the class holding the field type
 will be called ``ShippingType`` and the file will be stored in the default location
-for form fields, which is ``App\Form\Type``. Make sure the field extends
-:class:`Symfony\\Component\\Form\\AbstractType`::
+for form fields, which is ``App\Form\Type``.
+
+All field types must implement the :class:`Symfony\\Component\\Form\\FormTypeInterface`,
+but you should instead extend from :class:`Symfony\\Component\\Form\\AbstractType`,
+which already implements that interface and provides some utilities::
 
     // src/Form/Type/ShippingType.php
     namespace App\Form\Type;
@@ -53,8 +56,17 @@ for form fields, which is ``App\Form\Type``. Make sure the field extends
 Here, the return value of the ``getParent()`` function indicates that you're
 extending the ``ChoiceType`` field. This means that, by default, you inherit
 all of the logic and rendering of that field type. To see some of the logic,
-check out the `ChoiceType`_ class. There are three methods that are particularly
-important:
+check out the `ChoiceType`_ class.
+
+.. note::
+
+    The PHP class extension mechanism and the Symfony form field extension
+    mechanism are not the same. The parent type returned in ``getParent()`` is
+    what Symfony uses to build and manage the field type. Making the PHP class
+    extend from ``AbstractType`` is only a convenience way of implementing the
+    required ``FormTypeInterface``.
+
+There are three methods that are particularly important:
 
 .. _form-type-methods-explanation:
 

reference/forms/types/options/block_name.rst.inc

@@ -4,6 +4,11 @@ block_name
 **type**: ``string`` **default**: the form's name (see :ref:`Knowing which
 block to customize <form-customization-sidebar>`)
 
-Allows you to override the block name used to render the form type.
-Useful for example if you have multiple instances of the same form and you
-need to personalize the rendering of the forms individually.
+Allows you to add a custom block name to the ones used by default to render the
+form type. Useful for example if you have multiple instances of the same form
+and you need to personalize the rendering of the forms individually.
+
+If you set for example this option to ``my_custom_name`` and the field is of
+type ``text``, Symfony will use the following names (and in this order) to find
+the block used to render the widget of the field: ``_my_custom_name_widget``,
+``text_widget`` and ``form_widget``.

reference/forms/types/options/choice_label.rst.inc

@@ -16,8 +16,8 @@ more control::
             'no' => false,
             'maybe' => null,
         ],
-        'choice_label' => function ($choiceValue, $key, $value) {
-            if ($value == $choiceValue) {
+        'choice_label' => function ($value, $key, $choiceValue) {
+            if (true === $value) {
                 return 'Definitely!';
             }
 
@@ -28,9 +28,9 @@ more control::
         },
     ]);
 
-This method is called for *each* choice, passing you the choice ``$value`` and the
-``$key`` from the choices array (``$index`` is related to `choice_value`_). This
-will give you:
+This method is called for *each* choice, passing you the ``$value`` and 
+``$key`` from the choices array (additional ``$choiceValue`` is related to `choice_value`_). 
+This will give you:
 
 .. image:: /_images/reference/form/choice-example2.png
    :align: center