Remove experimental modules from core (or treat them like first class modules)

Just got bit by a backwards incompatible change while working on a D8 site. As this was during an upgrade from 8.0.4 to 8.0.5 I was quite shocked.

Background

I've been following Migrate module off and on for a couple of years. I'm familiar with the config entity definitions, processing plugin development, D6 ugprade support, D7 status, etc. I'm also aware of the upcoming change to plugins for definitions in 8.1.x. My overall impression of Migrate was that it is feature incomplete, lacks full documentation, and probably needs additional testing, etc. I think this is a view probably held by alot of Drupal developers. I also assumed that since it was in core, the major pieces of it would not be subject to change any longer, or they wouldn't have been included in Drupal core in the first place.

Backwards breaking changes

When updating to 8.0.5 my migrations were broken by this patch. I was surprised and googled around to find the policy for experimental modules and found https://www.drupal.org/core/experimental. This page has a section on versions at the bottom of the page, for "Alpha (e.g. 8.y.x-alpha)" and "Beta (e.g. 8.y.x-beta)" which I skipped since I was using 8.0.5, not an alpha or beta version of Drupal.

After talking on Twitter and IRC I found out that the policy is in fact that experimental modules are exempt from semantic versioning, or BC breaking changes. This is noted by explaining at the bottom of the "Alpha" section on the experimental modules page, that experimental modules in 8.1.x are considered alpha quality. This is very confusing since even the modules overview page reports the version of Migrate that I'm using as 8.0.5, which is not indicated as "Alpha" in any way.

Solution

I was pointed to #2656994: Experimental modules should have their own version numbers as solution to the problem and I was about to file a similar issue myself, but on further reflection I think the best solution is to remove experimental modules from core entirely (or treat them as first class modules), for the following reasons:

1) Drupal downloads appear to follow a semantic versioning scheme, which is associated with fairly strict standards for breaking backwards compatibility in a patch release. Drupal makes exceptions to that for some modules, which isn''t clearly explained. Semantic versioning is fairly strict about this policy, even invoking RFC strict definitions of MUST, MUST NOT, SHALL, SHALL NOT, etc. Most end users downloading Drupal are going to expect it to match, (or at least try to match) the policies defined with semantic versioning, which makes this a DX issue.

2) There is very little documentation explaining the policy for experimental modules, and it is not sufficiently linked/referenced. https://www.drupal.org/core/experimental is already somewhat confusing, but even worse, there is no link to that page in core, and no information on what experimental means on that page. The status report contains a short warning, but it doesn't define BC policy either.

3) Several people have tried to explain to me that experimental == BC breaks, just by definition, however this is a non-sequitur. By taking something, even if labeled experimental, and putting into what appears to be a semantically versioned release, it is entirely reasonable to assume that users will expect that there would be no BC breaking changes, even if the module does or doesn't work.

I.e. in the case above, I approached migrate cautiously because of the experimental status, but after thorough testing I found it to work well for my needs. There is a difference in saying "This may or may not work for your needs" and saying "This may or may not work for your needs, and even if it does, we may break it and it won't work after that"

4) I mentioned this earlier, but no where on https://www.drupal.org/project/drupal, https://www.drupal.org/drupal-8.0.5-release-notes, or http://cgit.drupalcode.org/drupal/plain/core/CHANGELOG.txt does it explain or link to the policy for experimental modules, or the BC policy. Further more there is no explanation of BC policy in core either.

5) Overall, I think the inclusion of 'experimental' modules in Core does not reflect well on Drupal 8 as a finished "product." Developers new to Drupal could be bitten by bad DX if they don't find our docs and figure out what they mean. End users could be bitten by bad UX if they enable/disable experimental modules. Why would we give end users something that we know might not work?

6) Finally back to point #1, no amount of renaming, warnings, labels, better docs, fixed version numbers will change the fact that this download (https://ftp.drupal.org/files/projects/drupal-8.0.5.tar.gz) looks like it doesn't contain any BC breaking changes, when in fact it does. For this reasons I think the only safe move is to remove experimental modules from core, unless we are willing to change the policy to treat then like first class modules.