Merge pull request #5108 from ethereum/payableWithdrawal

Explain address payable and withdraw.

docs/050-breaking-changes.rst

@@ -107,7 +107,10 @@ For most of the topics the compiler will provide suggestions.
   other way around is not allowed. Converting ``address`` to ``address
   payable`` is possible via conversion through ``uint160``. If ``c`` is a
   contract, ``address(c)`` results in ``address payable`` only if ``c`` has a
-  payable fallback function.
+  payable fallback function. If you use the :ref:`withdraw pattern<withdrawal_pattern>`,
+  you most likely do not have to change your code because ``transfer``
+  is only used on ``msg.sender`` instead of stored addresses and ``msg.sender``
+  is an ``address payable``.
 
 * Conversions between ``bytesX`` and ``uintY`` of different size are now
   disallowed due to ``bytesX`` padding on the right and ``uintY`` padding on

docs/types.rst

@@ -189,6 +189,13 @@ has the type ``address payable``, if ``x`` is of integer or fixed bytes type, a
 If ``x`` is a contract without payable fallback function, then ``address(x)`` will be of type ``address``.
 In external function signatures ``address`` is used for both the ``address`` and the ``address payable`` type.
 
+.. note::
+    It might very well be that you do not need to care about the distinction between ``address``
+    and ``address payable`` and just use ``address`` everywhere. For example,
+    if you are using the :ref:`withdrawal pattern<withdrawal_pattern>`, you can (and should) store the
+    address itself as ``address``, because you invoke the ``transfer`` function on
+    ``msg.sender``, which is an ``address payable``.
+
 Operators:
 
 * ``<=``, ``<``, ``==``, ``!=``, ``>=`` and ``>``