diff --git a/Migrating_To_1.0.0.md b/Migrating_To_1.0.0.md
new file mode 100644
index 0000000000..b26ae7c4d2
--- /dev/null
+++ b/Migrating_To_1.0.0.md
@@ -0,0 +1,36 @@
+# Migrating to 1.0.0
+
+If you've been using the former SDK (version `0.1.x` or `0.2.x`), there are some breaking changes 
+introduced in version `1.0.0`, namely:
+
+### Logger.Builder
+
+#### Before
+
+```java
+    logger = new LoggerBuilder()
+        .withName("my-application-name") // This would set the service name
+        .withNetworkInfoLogging(this)
+        .build("my-api-key");
+```
+
+#### After 
+
+```java
+    Datadog.initialize(context, "my-api-key");
+
+    // …
+
+    logger = new Logger.Builder()
+            .setNetworkInfoEnabled(true)
+            .setServiceName("android-sample-java") // Sets the service name
+            .setLoggerName("my_logger") // Sets the logger name (within the service)
+            .setLogcatLogsEnabled(true)
+            .build();
+```
+     
+#### Attributes
+
+The attributes were created or removed with the `Logger.addField()` or `Logger.removeField()` 
+methods. These methods were rename for consistency purposes, and are now  `Logger.addAttribute()` 
+ and`Logger.removeAttribute()`, but they will behave the same way as the old ones. 
\ No newline at end of file
diff --git a/README.md b/README.md
index 1ccba5d865..b3fa3a0086 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,9 @@ dependencies {
 
 ## Usage
 
+If you were a user of the SDK version `0.2.5` or lower, take a look at our 
+[Migration Guide](Migrating_To_1.0.0.md).
+
 ### Initial Setup
 
 Before you can use the SDK, you need to setup the library with your application
@@ -45,7 +48,7 @@ class SampleApplication : Application() {
 }
 ```
 
-### Initialization
+### Logger Initialization
 
 You can create a `Logger` instance using the dedicated builder, as follow:
 
@@ -85,7 +88,71 @@ follow:
     }
 ```
 
-> Note: All log level methods can have a throwable attached to them.
+> Note: All logging methods can have a throwable attached to them.
+
+### Adding context
+
+#### Tags
+
+Tags take the form of a single String, but can also represent key-value pairs when using a colon, and are 
+You can add tags to a specific logger as follow: 
+
+```kotlin
+    // This will add a tag "build_type:debug" or "build_type:release" accordingly
+    logger.addTag("build_type", BuildConfig.BUILD_TYPE)
+    
+    // This will add a tag "android"
+    logger.addTag("android")
+```
+
+You can remove tags from a specific logger as follow: 
+
+```kotlin
+    // This will remove any tag starting with "build_type:"
+    logger.removeTagsWithKey("build_type")
+    
+    // This will remove the tag "android"
+    logger.removeTag("android")
+``` 
+
+#### Attributes
+
+Attributes are always in the form of a key-value pair. The value can be any primitive, String or Date.
+You can add attributes to a specific logger as follow:
+
+```kotlin
+    // This will add an attribute "version_code" with an integer value
+    logger.addAttribute("version_code", BuildConfig.VERSION_CODE)
+    // This will add an attribute "version_name" with a String value
+    logger.addAttribute("version_name", BuildConfig.VERSION_NAME)
+```
+
+You can remove attributes from a specific logger as follow: 
+
+```kotlin
+    logger.removeAttribute("version_code")
+    logger.removeAttribute("version_name")
+``` 
+
+#### Local Attributes
+
+Sometimes, you might want to log a message with attributes only for that specific message. You can 
+do so by providing a map alongside the message, each entry being added as an attribute.
+
+```kotlin
+    logger.i("onPageStarted", attributes = mapOf("http.url", url))
+```
+
+In Java you can do so as follow:
+```java
+    mLogger.d(
+            "onPageStarted",
+            null, 
+            new HashMap<String, Object>() {{
+                put("http.url", url);
+            }}
+    );
+```
 
 ## Contributing