Instructions how to migrate to SeleniumLibrary

Author: pekkaklarck

README.rst

@@ -31,7 +31,6 @@ Keyword documentation
 __ http://robotframework.org/Selenium2Library/Selenium2Library.html
 __ http://robotframework.org/Selenium2Library/Selenium2Library-1.8.0.html
 
-
 Installation
 ------------
 
@@ -46,10 +45,48 @@ Install the legacy Selenium2Library 1.8.0 version::
 
     pip install robotframework-selenium2library==1.8.0
 
+Migrating to SeleniumLibrary
+----------------------------
+
+Existing Selenium2Library users should start migrating to the
+SeleniumLibrary_. For most users this should be a simple procedure:
+
+1. Install the latest Selenium2Library as explained above. This installs
+   both SeleniumLibrary and Selenium2Library, and in fact Selenium2Library
+   is nowadays just a thin wrapper for SeleniumLibrary.
+
+2. Execute tests normally to see are there problems.
+
+3. If problems are encountered, try on investigate why they occur. Possible
+   problems can be divided into two categories:
+
+   - If a keyword provided by the library itself has changed, take a look at
+     `SeleniumLibrary 3.0 release notes`_ to see is it a known backwards
+     incompatible change. If it isn't, you may have encountered a regression
+     that ought to be reported to `SeleniumLibrary issue tracker`_.
+
+   - If a library using Selenium2Library does not work anymore, it is likely
+     due to the large internal changes in SeleniumLibrary 3.0. Report the
+     problem to the maintainers of the broken library or fix the problem
+     yourself if you are the maintainer.
+
+   Regardless the problem, you can always ask help on various `support
+   channels`_.
+
+4. If no problems occur or after problems have been resolved, you can start
+   changing library imports to use ``SeleniumLibrary`` instead of
+   ``Selenium2Library``. Also all keyword usages in form like
+   ``Selenium2Library.Title Should Be`` need to be updated.
+
+5. After test data has been updated, Selenium2Library installation can
+   be removed altogether.
 
 .. _Robot Framework: http://robotframework.org
 .. _Selenium: http://seleniumhq.org
 .. _PyPI: https://pypi.python.org/pypi/robotframework-selenium2library
 .. _GitHub: https://github.com/robotframework/Selenium2Library
 .. _SeleniumLibrary: https://github.com/robotframework/SeleniumLibrary
 .. _pip: http://pip-installer.org
+.. _SeleniumLibrary 3.0 release notes: https://github.com/robotframework/SeleniumLibrary/blob/master/docs/SeleniumLibrary-3.0.0.rst
+.. _SeleniumLibrary issue tracker: https://github.com/robotframework/SeleniumLibrary/issues
+.. _support channels: http://robotframework.org/#support