diff --git a/README.md b/README.md
index 3ef6a34..5aaddba 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,40 @@
-## Upgrade path from Media Entity to Media (core)
+Upgrade path from Media Entity to Media (core)
+----
 
-@TODO
+## Important information about the 2.x branch
+
+This version of Media Entity is intended **only** to be used as a bridge to
+move to the new "Media" module included in Drupal core (>= 8.4.0). While the
+storage of media entities is the same, some aspects of the API have changed.
+Because of that, if you have an existing site using Media Entity 1.x, you need
+to follow the upgrade path indicated below in order to move to Media in core.
+
+## Upgrade instructions
+1. Backup your code and your database
+2. Test that you can successfully roll-back from the backup!
+3. Upgrade the codebase with:
+  - Core: >= **8.4.x**
+  - Media Entity: **8.x-2.x**
+  - All media entity providers: **8.x-2.x** (or use patches from #2860796: Plan for
+  contributed modules with Media Entity API in core). Note that the modules
+  Media Entity Image and Media Entity Document, if present, don't need to be
+  updated. Their configs will be updated by the main Media Entity updates.
+  - All modules that depend on or interact with Media Entity: **8.x-2.x**
+  - The new contrib module **Media Entity Actions**: **8.x-1.x**
+  - Note: If your site uses media entities with the "Generic" provider, make
+  sure you download to your codebase the **Media Entity Generic** module as
+  well.
+4. (Optional) Check that all requirements for the upgrade are met with
+  `drush mecu`.
+  **IMPORTANT**: Please note that if you are running DB updates with Drush 9
+  (between 9.0.0-alpha1 and 9.0.0-beta7), you are **strongly** encouraged to
+  use this command prior to running the updates. Drush 9 will not run the
+  requirements validation and will try to run the updates even if your site has
+  some of the requisites misconfigured. Executing the updates in that scenario
+  will likely break your site. This was fixed in Drush 9.0.0-beta8. Drush 8
+  users don't need to worry about this.
+5. Run the DB Updates, either by visiting `/update.php`, or using `drush updb`.
+6. Double-check **Media Entity** is uninstalled, and remove it from the
+  codebase. Remove also **Media Entity Image** / **Document**, if present.
+7. Run your automated tests, if any, or manually verify that all media-related
+  functionality on your site works as expected.