Migrate 2.0 needs completely rewritten documentation (advanced help, api.php, drupal.org pages). It's still a moving target, but we need to come back to it when things are stable.

CommentFileSizeAuthor
#8 migrate-2-doc.html_.txt8.74 KBchrisnovak

Comments

moshe weitzman’s picture

moshe weitzman commented

Yes, we need some docs here. But my hope is that we can add lots of inline docs on our migrate_example migrations. This is just more pleasant to maintain and more useful for implementers. SO, that gets my vote for area of focus here.

mikeryan’s picture

mikeryan
he/him
Primary language English
Location Pittsfield, MA, USA
commented

And the example migrations will also be the basis for simpletests...

lefnire’s picture

lefnire commented

Hear hear! I was disappointed to find no online docs & a practically empty README at first. However, working through migrate_example's code documentation (which is quite extensive, props!) proved muuuch better than the usual walkthrough-style docs. I hope this becomes common-place as documentation for all things API.

willmoy’s picture

willmoy commented

Umm... migrate_example is now empty? The module sounds great, though.

lefnire’s picture

lefnire commented

The migration classes are stored in the beer & wine .inc files, is why the .module is empty. These files are added in migrate_example.info via files[] = beer.inc & files[] = wine.inc

willmoy’s picture

willmoy commented

Ah, it wasn't that... it's not in HEAD only in 7--2:
http://drupalcode.org/viewvc/drupal/contributions/modules/migrate/migrat...

I will go and learn :)

mikeryan’s picture

mikeryan
he/him
Primary language English
Location Pittsfield, MA, USA
commented
Priority: Normal » Major

Bumping up the priority, as people start playing with Migrate 2 the lack of documentation is becoming more painful...

chrisnovak’s picture

chrisnovak commented
StatusFileSize
new migrate-2-doc.html_.txt8.74 KB

I started putting together some documentation on Migrate 2.0, please see attached HTML doc. Is this the right way to document? If you do find this helpful, I can add more- just let me know where I should be placing the documentation.

mikeryan’s picture

mikeryan
he/him
Primary language English
Location Pittsfield, MA, USA
commented

Thanks for the effort, but I do have ideas in mind for organizing the documentation once I get started on it.

bojanz’s picture

bojanz commented

I was thinking of writing an introduction blog post, and one detailing how to write custom destination handlers.

I can help with the docs once you have your structure in place.

mikeryan’s picture

mikeryan
he/him
Primary language English
Location Pittsfield, MA, USA
commented

I've outlined the Migrate V2 documentation, moving the Migrate V1 docs out of the way where they're less likely to confuse people. I will start filling this in over time...

slantview’s picture

slantview commented

It's mid-April and we still have extremely limited documentation on v2 especially for 6.x. I have recently lost a great deal of time to trying to use this module because there was a lot of people raving about v1 and had to abandon the work because of problems of getting things to work correctly and time it was taking to get it done.

Please, please get this documented. It looks great and I love doing the OO code, but I just could not make it work correctly. I would love to give it another chance on the next round of migration work.

Thanks for all your hard work, I know how hard it is to maintain these projects!

drewish’s picture

drewish commented

Personally I've found the beer and wine examples to be mildly interesting but I'd prefer much better class and method level documentation. The examples will hint at something and I'll go looking to find more but end up having to read the source because the actually code has no documentation. It's actually bad enough that I'm ready to just go hand roll migration code.

mikeryan’s picture

mikeryan
he/him
Primary language English
Location Pittsfield, MA, USA
commented

Writing documentation is a time-consuming process, and it's exponentially related to the size and complexity of the thing being documented. I did put some time in today on the documentation, but there's still a long way to go.

The best way to help the documentation move forward is to open support requests with questions about specific things you need help with. Going forward, I'll try to add/edit the relevant documentation in response to such requests, and that way we'll get the things that people really need help with written up first, rather than slogging linearly through parts that may or may not be of interest to many people.

Thanks.

mikeryan’s picture

mikeryan
he/him
Primary language English
Location Pittsfield, MA, USA
commented
Status: Active » Fixed

I think the documentation is mostly there - any specific holes should have their own issues in the queue.

Status: Fixed » Closed (fixed)

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