Describe Migration plugins and their relationship to source, process and destination plugins

Follow-up to #2687003: Remove references to nonexistent functionality from migrate.api.php, #2676222: Move MigrationInterface out of the migrate\Entity namspace now they are plugins and #2625696: Make migrations themselves plugins instead of config entities

Problem/Motivation

Migrations are plugins no longer configuration entities - the docs have been fixed in #2687003: Remove references to nonexistent functionality from migrate.api.php to be more correct. However, exact what a migration plugin is and how it relates to source, process and destination plugins can be improved. Specifically:

#2687003-19: Remove references to nonexistent functionality from migrate.api.php by @xjm

Thanks @alexpott.

I applied the patch and read the whole docblock locally but I am still very confused: Are "migration plugins" a separate plugin type from source, process, and destination? If so, I think that we should explicitly state that Migrate uses four different types of plugins. Because on first read I thought "migration plugin" was a general header summarizing all three types, but the relationship between "migration plugins" and the source, process, and destination plugins is not clear.

I think this first paragraph is fine still:

 * @section overview Overview of migration                                      
 * Migration is an                                                              
 * @link http://wikipedia.org/wiki/Extract,_transform,_load Extract, Transform, Load @endlink                                                                  
 * (ETL) process. For historical reasons, in the Drupal migration tool the      
 * extract phase is called "source", the transform phase is called "process",   
 * and the load phase is called "destination". 

I do not think it needs to be directly followed by this exact paragraph:

 * Source, process, and destination phases are each provided by plugins.        
 * @ref sec_source extract data from a data source in "rows", containing        
 * "properties". Each row is handed off to one or more series of                
 * @ref sec_process, where each series operates to transform the row's          
 * properties in order to prepare them for the @ref sec_destination. After all  
 * the properties are processed, the resulting row is handed off to a           
 * destination plugin, which saves the data. Source, process and destinations   
 * plugins are brought together to extract, transform and load a specific type  
 * of data by @ref sec_migrations. Migration plugins also contain information on                                                                               
 * dependencies.

The information about plugins can easily be removed from that paragraph. What is important for the initial section is to define the terms "source", "process", "destination", "rows", and "properties". Whether they are plugins or not is implementation.

And if "migration plugins" are a separate category from the other three, then we need a much clearer definition of what they are, and I'd suggest a different name because it would seem to encompass all types of plugins involved in Migrate. If they are not a separate thing, then we should instead say that they are divided into three types.

I can try to help rewrite the docs too once I understand it.

And #2687003-20: Remove references to nonexistent functionality from migrate.api.php by @alexpott

I'm just going to try to write everything here.

A migration is the ability to extract something from the source, transform it to make it compatible with the destination and then load (save) it there. This whole thing in D8 is a MigrationPlugin. The different phases: extract, transform, and load are also plugins (which plug in to the Migration plugin - migrate is kinda like views in this respect). So there are four types of plugin:

1. Migration plugins: \Drupal\migrate\Plugin\Migration : \Drupal\migrate\Plugin\MigrationInterface
2. Source plugins: \Drupal\migrate\Plugin\migrate\source\SourcePluginBase : \Drupal\migrate\Plugin\MigrateSourceInterface
3. Process plugins: \Drupal\migrate\ProcessPluginBase : \Drupal\migrate\Plugin\MigrateProcessInterface
4. Destination plugins: \Drupal\migrate\Plugin\migrate\destination\DestinationBase : \Drupal\migrate\Plugin\MigrateDestinationInterface

I think that the Migration plugin is well named. If we ever have something that configures a set of migration plugins then you'll be plugging these in to set the whole thing up. I think it is shame that we didn't change the other plugins to match the ETL (extract, transform, load) language as that is the lingua franca of tools that perform similar tasks.

In a migration a row is extracted from source by the source plugin. The source can a Drupal 6 database, an XML file or whatever. The process plugins then transform properties of the row, or can mark it to be skipped (if deduping for example). Process plugins can also determine that a stub needs to be created - for example if a term has a parent of term that does not yet exist. Once the row has been transformed it is handed to the destination plugin that simply loads it into (saves) the Drupal 8 site. This whole ETL process is configured by the migration plugin.

Proposed resolution

Fix it

Remaining tasks

User interface changes

API changes

Data model changes