magento/devdocs#: Configure migration. Changes.

[atwixfirster]

Purpose of this pull request

Regarding to Magento best practices we should not edit core files except when you contribute 😸

Configure migration contains recommendation to directly edit Data Migration Tool config files. This pull request replaces mentioned recommendations regarding to Magento best practices.

Affected DevDocs pages

• https://devdocs.magento.com/guides/v2.2/migration/migration-tool-configure.html
• https://devdocs.magento.com/guides/v2.3/migration/migration-tool-configure.html

whatsnew
Added best practices for configuring the migration tool.

[devops-devdocs]

An admin must run tests on this PR before it can be merged.

[rogyar]

Hi @atwixfirster. Thank you for this way of thinking. First of all, your advice is very useful. However, we don't have a convincing explanation of why should we overcomplicate the process and create a separate module. Let me shed some light on it.

First of all, by copying *.xml.dist files to *.xml we don't edit the core, we just add new files. The same happens when you copy phpunit.xml.dist to phpunit.xml in case of configuring the automated tests.
In this particular case, I would say, the problem is in bringing manual changes to the vendor directory. Ideally, this directory should be modified only by composer. It's not a sort of "good" practice but MUST in case if you use continuous delivery for your environments.
If you use continuous delivery, you install the codebase from scratch on every deployment (the vendor directory is generated by composer completely). That's why all your changes in vendor/magento/data-migration-tool/ will be lost.
There are two obvious ways of solving this issue:

• a separate module in app/code directory with proper configs under version control.
• a separate module installable via composer with the proper configs (in this case you need an extra repository or modified composer install flow).

Providing changes in vendor/magento/data-migration-tool is acceptable only in case if you run the migration process locally and if you are not going to put your changes under version control.

[atwixfirster]

Hi, @rogyar !

Thank you VERY MUCH for the explanation.

I've implemented your suggestions. Could you please verify them and let me know what do you think?

Have a wonderful day!

[rogyar]

Awesome, thank you

[atwixfirster]

@jeff-matthews, all your suggestions have been implemented. Please review.

Many thanks as always :)

[jeff-matthews]

Almost there @atwixfirster ;). Just a few more edits please.

[jeff-matthews]

@atwixfirster, there are also some markdown syntax errors:

rake test:md
Testing Markdown style with mdl ...
guides/v2.2/migration/migration-tool-configure.md:70: MD009 Trailing spaces
guides/v2.3/migration/migration-tool-configure.md:70: MD009 Trailing spaces

A detailed description of the rules is available at https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md

The Markdown linter has found 4 issues

[atwixfirster]

@jeff-matthews, let's try again :)

Thanks

[jeff-matthews]

Confirmed! Thanks @atwixfirster.

[jeff-matthews]

running tests

[ghost]

Hi @atwixfirster, thank you for your contribution!
Please, complete Contribution Survey, it will take less than a minute.
Your feedback will help us to improve contribution process.