Problem/Motivation

Portions of the d.o. migration documentation need updating and reorganization. The issues include out-of-date content, poor organization (particularly in the less technical areas), and missing content.

I think the goal here is to provide useful documentation for three primary types of users:

  1. Those interested in running migrations.
  2. Those interested in developing migrations.
  3. Those interested in contributing.

We currently have two main areas of documentation:

  1. https://www.drupal.org/upgrade/migrate - most of this information is on "Running Migrations", but it needs some work.
  2. https://www.drupal.org/node/2127611 (Migrate API)

I'm proposing that information for those interested in contributing be located within the "Running Migrations" section, so that we can keep the "Migrate API" section clearly focused on API documentation.

Proposed resolution

I've created a GoogleDoc with the existing outlines in the two main areas (Running Migrations and Migrate API), some brief info about some of the top-ish level pages, as well as some proposed changes to the structure of the "Running Migrations" tree. Feel free to leave comments on the GoogleDoc or below, I'll do my best to compile everything in a way that makes sense.

Remaining tasks

Child issues contain documentation todos. Not all of them are listed here in this issue summary.

Todos from #11.2 which are not covered by child issues:

Additional topics (new)

Writing migrations for custom/contributed modules (new) - #2914500: Add documentation for writing custom/contrib modules

  • Use core modules as examples, including source plugins, tests, etc… (a bit of a start here: https://www.drupal.org/node/2342695) (new)
  • Examples
  • When to use templates
  • Link to API docs

User interface changes

None.

API changes

None.

Data model changes

None.

Comments

ultimike created an issue. See original summary.

ultimike’s picture

ultimike
Primary language English
Location Florida, USA
CreditAttribution: ultimike at DrupalEasy commented
Issue summary: View changes

Reformated GoogleDoc link.

ultimike’s picture

ultimike
Primary language English
Location Florida, USA
CreditAttribution: ultimike at DrupalEasy commented
Issue summary: View changes

Fixed typo above.

quietone’s picture

quietone CreditAttribution: quietone commented

Looks good, just a few questions.

  1. The reorganization is just for the 'Admin & Security' doc and not elsewhere?
  2. Where will documentation for migrate_drupal go? The only reference I see in the google doc refers to the generation of dump files.
ultimike’s picture

ultimike
Primary language English
Location Florida, USA
CreditAttribution: ultimike at DrupalEasy commented

@quietone,

No - not at all.

There are currently 2 main areas of Migration documentation on Drupal.org:

  1. Migrate API (in the "Develop for Drupal" section)
  2. Upgrading from Drupal 6 or 7 to Drupal 8 (in the "Admin and Security" section)

The documentation for migrate_drupal will be in the Migrate API area.

-mike

quietone’s picture

quietone CreditAttribution: quietone commented

Thx

willwh’s picture

willwh CreditAttribution: willwh at Drupalize.Me commented

Hi Guys,

This landed today: https://www.drupal.org/node/2691023, which removes some fairly significant functionality for running partial migrations.

There are lots of mentions of drush migrate-import --configure-only in the documentation, that are going to require updates.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

quietone’s picture

quietone CreditAttribution: quietone commented
Status: Active » Needs review

I've gone through the googledoc and compared with the current state of the documentation. I updated the googledoc locally only to find that cutting and pasting my changes into the googledoc totally messes up the formating and makes the document unreadable.

So, in summary nearly all the suggested reorganization has taken place. The two expceptions are

  1. The new sections. Makes sense they aren't there to organize
  2. What the 'top' page for the Running migrations should be. ultimike suggested it should be the page that explains the terms, upgrade, update and migrate. That page is now in the Drupal 7 documentation, making it hard to find if you are upgrading to Drupal 8. Go to Upgrade to Drupal 7 scroll to the bottom and find Updating and upgrading Drupal core. Seems out of place to me.

This is a list of the new sections, also listed in the googledoc.

  • Additional topics (new)
  • Contributing (new)
    • Testing migrations (new)
      • Things to look out for in D6 and D7 (new)
    • How to report your findings (new)
  • Writing migrations for custom/contributed modules (new)
    • Use core modules as examples, including source plugins, tests, etc… (a bit of a start here: https://www.drupal.org/node/2342695) (new)
    • Examples (new)
    • When to use templates (new)
    • Link to API docs (new)

There are issues for adding documentation to the codebase for the migrate plugins. The intention is to have examples of special cases in the handbook.

Next Steps:
Discuss what to do about items 1 and 2 above.

Links:
The Drupal 8 upgrade pages, https://www.drupal.org/docs/8/upgrade
The Drupal 8 Migrate API docs, https://www.drupal.org/docs/8/api/migrate-api
The Drupal 7 upgrade page, https://www.drupal.org/docs/7/upgrade-to-drupal-7

quietone’s picture

quietone CreditAttribution: quietone commented
Assigned: ultimike » Unassigned
quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Assigned: Unassigned » quietone
Status: Needs review » Needs work
Issue tags: +Needs issue summary update

Assigning to myself to update the IS.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented

Made a child issue for item #11.2 , #2914474: Placement of 'top' page explaining upgrade, upgdate and migrate

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Issue summary: View changes

Copied the todo list from #11.2 to the IS and added the sub issues created for each item, so far. Still more to do.

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Issue summary: View changes

Fix formatting.

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Issue summary: View changes

Specifying dependencies (related: https://www.drupal.org/node/2214325). No action needed for this, See #9 in that issue.

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Issue summary: View changes

Additional topic include an item for 'Others'. None have been added since this issue was created 2 years ago, so ultimike did a great job of identifying what it needed. Marking that with a suggestion to add a new issue if you think of a topic that needs to be added to the docs.

That addresses all the issue in the first section of the Remaining tasks, 'Additional topics (new)'.

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Issue summary: View changes

Fix the formatting in the IS again.

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Title: Reorganization of (some) d.o. migration documentation » [Meta] Reorganization of (some) d.o. migration documentation
Issue summary: View changes

Created child issues for the 2 remaining items in the todo list.

Now all the todo items have a child issue or have been fixed. Hopefully, now that this is in smaller chunks we can get this done.

Adding meta to the title.

And thanks to masiplia for offering to help which, in turn, got me to update the issue!

quietone’s picture

quietone CreditAttribution: quietone as a volunteer commented
Assigned: quietone » Unassigned

Unassigning.

masipila’s picture

masipila CreditAttribution: masipila as a volunteer commented
Issue summary: View changes

Cleaned up issue summary.

masipila’s picture

masipila CreditAttribution: masipila as a volunteer commented
Status: Needs work » Fixed

I've now reorganized the Upgrade to Drupal 8 guide and Migrate API guide.

This meta was about reorganizing / adding new pages. I moved the pending 'add new pages' tasks to be children of the meta issue #2561243: [meta] Migration system documentation so that we have only one meta for the missing pages.

Closing this meta as this doesn't have any child issues anymore.

Cheers,
Markus

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.