Fill in @defgroup/topic docs for Migration overview

I am at least temporarily moving this into the migration system issue queue. I am kind of clueless about migration, so it would really be better if one of the maintainers could take a first pass at writing an overview for developers of this topic.

Since this is going into an api.php file as a @defgroup, the idea is to give a basic overview and link to more information (on drupal.org, or other topics) rather than providing a comprehensive tutorial. Also, relevant classes and functions should be added to the topic with @ingroup (see issue summary above).

If you click through to the parent issue, and look at the "child issues" sidebar, you can find other issues that have been completed to give you an idea of what is needed. Or start at the api.drupal.org landing page for Drupal 8, and click into topics (nearly all of them are done now, except this one and a few others that are still open on the parent issue).

And if you prefer, you could give an outline of what needs to be written here, or a link to the relevant existing more comprehensive documentation, and I can give it a shot. Thanks!

OK... Thanks, I think I know what is going on in Migrate now, so that gave me enough information to go to work writing.

Here's a new patch:
- Moved the defgroup into migrate.api.php instead of core.api.php
- Expanded the docs there quite a bit
- Reduced the number of @ingroup so it only includes annotation classes, base classes, interfaces, plugin managers, and entity classes/interfaces.
- The @ingroup should have been @ingroup migration

So this is a completely new patch. An interdiff is not useful, I think?

chx reviewed this in IRC. Here's a new patch:
- take out most of the mention of load plugins (not widely needed)
- I had not quite gotten the process plugin description right

New patch and interdiff...

weird. Message #8 says the patch in #6 failed testing, but it actually passed (meaning in this case: the patch applied and didn't introduce PHP errors; it's all docs).

Good catch! Fixed that. Had to rewrap the paragraph. Patch and interdiff attached.

Yes, I think the pages that are linked to on d.o are at least a good start/skeleton.

One thing I noticed while making this patch is the inconsistency between the names and locations/namespaces of the interfaces, base classes, and annotation classes. Take a look at the 3 sections about the plugin types:

a) Source:

+ * \Drupal\migrate\Plugin\MigrateSourceInterface and usually extend
+ * \Drupal\migrate\Plugin\migrate\source\SourcePluginBase. They are annotated
+ * with \Drupal\migrate\Annotation\MigrateSource annotation, and must be in

b) Process:

+ * \Drupal\migrate\Plugin\MigrateProcessInterface and usually extend
+ * \Drupal\migrate\ProcessPluginBase. They are annotated
+ * with \Drupal\migrate\Annotation\MigrateProcessPlugin annotation, and must be

c) Destination:

+ * \Drupal\migrate\Plugin\MigrateDestinationInterface and usually extend
+ * \Drupal\migrate\Plugin\migrate\destination\DestinationBase. They are
+ * annotated with \Drupal\migrate\Annotation\MigrateDestination annotation, and

I guess the interfaces are consistently named.

Two base classes are in their full Plugin\migrate\* directories; one is in the base migrate src directory.

One annotation class ends in "Plugin" and the other two do not.

Anyway, I'll just point this out and leave it to you to (hopefully) fix. If you do, please change the links -- the ProcessPluginBase class was apparently moved recently and links in various class headers were not changed (fixed in this patch).