diff --git a/README.md b/README.md
index bbd0353..07fcba9 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,9 @@ Full documentation can be found at [http://opensource.box.com/spout/](http://ope
 * PHP extension `php_zip` enabled
 * PHP extension `php_xmlreader` enabled
 
+## Upgrade guide
+
+Version 3 introduced new functionality but also some breaking changes. If you want to upgrade your Spout codebase from version 2 please consult the [Upgrade guide](UPGRADE-3.0.md). 
 
 ## Running tests
 
diff --git a/UPGRADE-3.0.md b/UPGRADE-3.0.md
index ef7eb07..6830254 100644
--- a/UPGRADE-3.0.md
+++ b/UPGRADE-3.0.md
@@ -58,6 +58,24 @@ $row2 = WriterEntityFactory::createRow([$cell1, $cell2]);
 $writer->addRows([$row1, $row2]);
 ```
 
+Namespace changes for styles
+-----------------
+The namespaces for styles have changed. Styles are still created by using a `builder` class.
+
+For the builder, please update your import statements to use the following namespaces:
+
+    Box\Spout\Writer\Common\Creator\Style\StyleBuilder
+    Box\Spout\Writer\Common\Creator\Style\BorderBuilder
+
+The `Style` base class and style definitions like `Border`, `BorderPart` and `Color` also have a new namespace.
+
+If your are using these classes directly via an import statement in your code, please use the following namespaces:
+
+    Box\Spout\Common\Entity\Style\Border
+    Box\Spout\Common\Entity\Style\BorderPart
+    Box\Spout\Common\Entity\Style\Color
+    Box\Spout\Common\Entity\Style\Style
+
 Handling of empty rows
 ----------------------
 In 2.x, empty rows were not added to the spreadsheet.