--- EV/EV.pm	2010/10/21 02:46:59	1.128
+++ EV/EV.pm	2010/10/21 15:13:42	1.129
@@ -79,6 +79,37 @@
 and still be faster than with any other event loop currently supported in
 Perl.
 
+=head2 PORTING FROM EV 3.X to 4.X
+
+EV version 4 introduces a number of incompatible changes summarised
+here. According to the depreciation strategy used by libev, there is a
+compatibility layer in place so programs should continue to run unchanged
+(the XS interface lacks this layer, so programs using that one need to be
+updated).
+
+This compatibility layer will be switched off in some future release.
+
+All changes relevant to Perl are renames of symbols, functions and
+methods:
+
+  EV::loop          => EV::run
+  EV::LOOP_NONBLOCK => EV::RUN_NOWAIT
+  EV::LOOP_ONESHOT  => EV::RUN_ONCE
+
+  EV::unloop        => EV::break
+  EV::UNLOOP_CANCEL => EV::BREAK_CANCEL
+  EV::UNLOOP_ONE    => EV::BREAK_ONE
+  EV::UNLOOP_ALL    => EV::BREAK_ALL
+
+  EV::TIMEOUT       => EV::TIMER
+
+  EV::loop_count    => EV::iteration
+  EV::loop_depth    => EV::depth
+  EV::loop_verify   => EV::verify
+
+The loop object methods corresponding to the functions above have been
+similarly renamed.
+
 =head2 MODULE EXPORTS
 
 This module does not export any symbols.