Increase reliability of upgrade path to Media in core

Broadened a bit the scope of the issue.

For example, the drush command we are providing is not going to be compatible with Drush 9, we should address that.

Postponing this on #2877383: Add action support to Media module

Re-purposing this to make this a plan and wrap all other little bugs that are bubbling up.

+++ b/tests/src/Functional/CoreMediaUpdatePathRequirementsTest.php
@@ -0,0 +1,46 @@
+    // The fixture had the 1.x versions of several media type providers
+    // installed.
...
+    // The fixture had a generic media type, but Media Entity Generic is not
+    // present in the current code base.

If I understand correctly, this test assumes a codebase in a state that matches the fixture (drupal-8.3.7-media-suite). Can't we try to avoid that? It will quickly start to get very difficult to manage that while running tests. (By the way, I'm not sure if it's possible at all)

In other words, if you are running this test in a codebase with media_entity_instagram 2.x, the assert

$assert->pageTextContains('Some modules that depend on media entity were not updated or uninstalled.');

will fail.

However, if we are running tests that use the fixture 8.4 (that assumes different codebases), we'll need to update the codebase before running the test.

Actually, let's move the discussion about patch #2 to #2916821: Improve automated tests of Media Entity upgrade path to Media core and keep this issue as a plan.

(I have moved the patch there and re-commented what I said above)

Added the link to the manual testing spreadsheet to the IS.

Regarding:

Review all (or most of the) plugin contrib modules with 2.x branches, making sure there's documentation about when to use 1.x and when to use 2.x.

I went through the list in #2860796: Plan for contributed modules with Media Entity API in core and checked all projects that have 2.x branches available. Some of them have no information about when to use 1.x versus 2.x, and others have some information but it's still not clear in some cases that you can indeed use the 1.x branch with core 8.4.x.

My suggestion is to make that very explicit, because users are already getting confused by the mix of versions.

A possible wording of text to be used could be something like:

<h2>Which version should I use?</h2>

Regardless of your Drupal core version, if you are using the 1.x branch of <a href="https://www.drupal.org/project/media_entity">Media Entity</a>, you should continue using the 1.x branch of this module.

If you are building a new site and want to use the new Media in core (>= 8.4.0), you should use the 2.x branch of this module.

If you have an existing site with Media Entity 1.x and you want to upgrade to Media in core, you need to update the code of this module from the 1.x branch to the 2.x branch. Please check the upgrade instructions on the <a href="https://www.drupal.org/project/media_entity">Media Entity</a> module page for more information on that process.

Below are the modules that I checked and their maintainers (as stated on the project page):

Audio: KO (slashrsm)
Carto: OK
Crop API: OK
Document: N/A
Dropzonejs: KO* (zkday)
Entity Browser: OK
Facebook: KO* (dawehner)
Flickr: KO (dakku)
GoogleDocs: KO* (dakku)
Instagram: KO* (slashrsm)
Media Expire: KO* (chr.fritsch)
Pinterest: KO* (bonus)
Riddle Marketplace: KO* (chr.fritsch)
Slideshow: KO* (slashrsm)
Tumblr: KO (dawehner)
Twitter: KO* (slashrsm)
Video: KO* (Daniel Korte)
Video Embed Field: KO (Sam152)

OK: Info is clear on the project page
KO: There is no indication on the project page
KO*: It's mentioned, but it could be clearer that 1.x is OK with 8.4

@Maintainers: could you please check the project page and see if the text can be improved? Thanks!

I could ping directly all maintainers listed above, with the exception of:

• zkday (dropzonejs)
• dakku (flickr, googledocs)
• bonus (pinterest)

Does anyone have means to reach them, or know other people with access to these project pages? If not, I can also create an issue on the project's issue queue.

Thanks @Sam152 and @dawehner!

Re:

It would be nice to be able to link to a handbook page explaining things with more details.

You can! :)
There is a brief documentation guide about the core Media module, and a specific FAQ page about the most common questions. By the way, feedback about the text there is more thank welcome! Please let me know if you see any information missing or not clear enough!

Added #2921983: Core upgrade path does not account for views that validate by media bundle to the IS.

So I believe #2923400: Source data for Image media entities lost during upgrade to core's Media module should definitely be here as well.

There should also be a solution for sites using EXIF image handling and want to upgrade. Added #2925712: Media Entity Image 8.x-2.x - core Media API roadmap & integration to the IS as well.

Added #2923372: Upgrade fails if site has "medium" image style missing to the IS.

With that, I believe we are in a position of saying that the remaining goals for "upgrade path stability" are:
- Achieving "confidence" with the manual testing
- Providing a solution for sites using EXIF mapping (#2925712: Media Entity Image 8.x-2.x - core Media API roadmap & integration)

IS housekeeping

Added the last issues to the IS as well.

Added #2927149: Updating from Media Entity to core Media creates a new video source field to the list of must-haves.

Replaced #2925712: Media Entity Image 8.x-2.x - core Media API roadmap & integration by #2927481: Integrate sites relying on EXIF metadata handling in the media upgrade path on the IS, which better reflects the issue.

Added #2877378: Add token replacements for Media to the list of must-haves, now that we know that there would be missing tokens.

Thanks @tstoeckler!
I have added the new ones to the IS as well.

I think we may be very close to considering this "stable enough" for a beta. Leaving this in Needs Review for now.

After the agreement that tokens should not be considered as part of the API (see #2877378: Add token replacements for Media), I have downgraded the tokens-related issue to a "could have", which can be treated in a follow-up without necessarily blocking stability of ME 2.x. In any case, I have added a note to the upgrade instructions on the module page and on the handbook page, with instructions about how to proceed if a site relies on media tokens.

With that, I feel all important issues are at this point solved, so IMHO we can considered this as "done", at least to start a beta phase and encourage more testing and feedback.

Thanks everyone!

Filed #2935505: Inform users upgrading to Media in core that the Token module should be used after the upgrade as a follow-up to include the token recommendation in the upgrade process itself.

I've tried to reproduce this but couldn't.

- Clean 8.6.x install
- Enable Media and Content Translation, add a second language
- Mark media Image bundle as translatable, select the file itself as translatable
- Create a Media entity with file A
- Edit the media entity and replace file A with file B
- Create a translation of the entity, replacing the file B with file C

Everything seems to work fine, do you see something different from your testing?