Document upgrade path to Media in core

> Clear caches AFTER the code has been updated, but BEFORE running the DB updates

That means it is vital to first update the code, then clear the cache, and the run the db updates?

In that case, maybe a note could be added that you should use drush `drush pm-updatecode` instead of `drush pm-update`?

This looks good, should we put this on the project homepage?

I feel like there's an important step missing: remove the contrib "media" module before updating.

Comment on #4, bullet 3: I've been trying to find 2.x branches for media_entity_document and media_entity_image, since they aren't on the list of patches.

#2860796-18: Plan for contributed modules with Media Entity API in core mentions that these modules will be handled in media_entity, but it's not at the top of the issue as part of the table.

I'm not sure that we can call out these modules as "don't worry about these" either, because if you're using composer to manage things you'll need to update media_entity_image 8.x-1.x #2916854: Allow inclusion in a Composer-built code base alongside Media Entity 1.x in order to be able to get media_entity 2.x via composer.

media_entity_document will need a similar update as well.

My preference would be, for consistency's sake, to create 8.x-2.x branches of both these modules with the composer.json updates.

re: composer, looks like these were recently fixed:

• http://cgit.drupalcode.org/media_entity_image/commit/?id=3264d04a39d342c...
• http://cgit.drupalcode.org/media_entity_document/commit/?id=b98ec72e303d...

And the updated text for #4 is much clearer, thanks!

+++ b/README.md
@@ -1,3 +1,40 @@
+Upgrade path from Media Entity to Media (core)
+----
 
...
+## Important information about the 2.x branch

I think this part is not really lisible because that display two *BIG* title at same level and strike mes eyes :D

What do you think about write directly

# Upgrade path from Media Entity to Media (core)

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

That seems more clear.

<3 LGTM we can call this RTBC I think.

Just I add mention of https://www.gitbook.com/book/drupal-media/drupal8-guide/details That's should be great to not forget this page and add mentions of Upgrade path.

If you have deleted the core default "medium" image style, you will need to re-create it before running the DB updates, because media config has a dependency on it.

If the image style is not present, an error is thrown during media_entity_update_8201:
Configuration objects provided by media have unmet dependencies: core.entity_view_display.media.image.default (image.style.medium)

@marcoscano FWIW, I had these results after updating Drupal from 8.3.7 -> 8.4.2, updating media_entity to 8.x-2.x, and adding media_entity_actions:

rat:s2923372 ben$ drush mecu
Symfony\Component\DependencyInjection\Exception\ServiceNotFoundException: You have requested a non-existent service "media_entity.cli". in [error]
/Users/ben/Sites/media-tests/s2923372/core/lib/Drupal/Component/DependencyInjection/Container.php:151
Stack trace:
#0 /Users/ben/Sites/media-tests/s2923372/core/lib/Drupal.php(158):
Drupal\Component\DependencyInjection\Container->get('media_entity.cl...')
#1 /Users/ben/Sites/media-tests/s2923372/modules/media_entity/media_entity.drush.inc(71): Drupal::service('media_entity.cl...')
#2 /Users/ben/.composer/vendor/drush/drush/includes/command.inc(422): drush_media_entity_check_upgrade()
#3 /Users/ben/.composer/vendor/drush/drush/includes/command.inc(231): _drush_invoke_hooks(Array, Array)
#4 /Users/ben/.composer/vendor/drush/drush/includes/command.inc(199): drush_command()
#5 /Users/ben/.composer/vendor/drush/drush/lib/Drush/Boot/BaseBoot.php(67): drush_dispatch(Array)
#6 /Users/ben/.composer/vendor/drush/drush/includes/preflight.inc(66): Drush\Boot\BaseBoot->bootstrap_and_dispatch()
#7 /Users/ben/.composer/vendor/drush/drush/drush.php(12): drush_main()
#8 {main}
rat:s2923372 ben$ drush cr
Cache rebuild complete.                                                                                                                    [ok]
rat:s2923372 ben$ drush mecu
✓ SUCCESS: All upgrade requirements are met and you can proceed with the DB updates.                                   [ok]
Drupal core is the correct version (>= 8.4.0). [8.4.2 detected]                                                                            [ok]
The contributed "Media" module is not installed.                                                                                           [ok]
All provider plugins and modules depending on media_entity are up-to-date.                                                                 [ok]
The "Media Entity Actions" module is available.                                                                                            [ok]
rat:s2923372 ben$

I.e., seems like adding a cache-clear instruction as suggested in #5 is warranted.

I've run some test upgrades and they conform perfectly to the instructions you have here, @marcoscano. As far as I'm concerned, this should be RTBC, but I'm not making the state change myself in case there's something I'm missing.