From 927cdb3170c27f8fe7bf105a8479e286bcdc642e Mon Sep 17 00:00:00 2001
From: chriseth <chris@ethereum.org>
Date: Thu, 27 Sep 2018 11:16:50 +0200
Subject: [PATCH] Explain address payable and withdraw.

---
 docs/050-breaking-changes.rst | 5 ++++-
 docs/types.rst                | 7 +++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/docs/050-breaking-changes.rst b/docs/050-breaking-changes.rst
index 1c12daa8f..b49dd1e09 100644
--- a/docs/050-breaking-changes.rst
+++ b/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
diff --git a/docs/types.rst b/docs/types.rst
index 03896a96c..c96b27c40 100644
--- a/docs/types.rst
+++ b/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 ``>``