NEW Add migration task from older versions of the module

[GuySartorelli]

Description

Provides a migration task and docs for upgrading from 2.x or 3.x to 4.x

Dependencies

Requires https://github.com/silverstripe/silverstripe-framework/pull/11171 for one of the unit tests.

Manual testing steps

1. Set up some links with v3 of the module
   • be as creative as you want with it, hopefully the guide tells you how to deal with your scenario.
   • Minimally have a has_one relation to Link and a has_many relation to Link using gridfield to manage the has_many.
2. Use the upgrade guide. Where it says to update to ^4 obviously you'll need to pull in this PR instead.

Issues

• https://github.com/silverstripe/silverstripe-linkfield/issues/228

Pull request checklist

• [x] The target branch is correct
  • See picking the right version
• [x] All commits are relevant to the purpose of the PR (e.g. no debug statements, unrelated refactoring, or arbitrary linting)
  • Small amounts of additional linting are usually okay, but if it makes it hard to concentrate on the relevant changes, ask for the unrelated changes to be reverted, and submitted as a separate PR.
• [x] The commit messages follow our commit message guidelines
• [x] The PR follows our contribution guidelines
• [x] Code changes follow our coding conventions
• [x] This change is covered with tests (or tests aren't necessary for this change)
• [x] Any relevant User Help/Developer documentation is updated; for impactful changes, information is added to the changelog for the intended release
• [ ] CI is green

[GuySartorelli]

Retargetted to 4.0 so it gets included in the initial stable release.

[GuySartorelli]

Do a test I got this warning which is correct because I missed a step:

Migrating has_many relations.
has_one relation 'SilverStripe\LinkField\Models\Link.MyPage still exists. Cannot migrate has_many relation 'Page.MyPhoneLinks'.

However the rest of the script still processed and now my data is possibly is a weird state. What should have happened is the script should have stopped immediately and told me to fix my issues.

I don't think it matters too much, since you should create a snapshot before starting which you can roll back to. But it is friendlier to rollback for you in this case, since has_many is explicitly declared as opposed to the has_one stuff. I'll make this rollback for you.

Edit: This now throws an exception, which will trigger the rollback, and tell you that it rolled back.

[GuySartorelli]

Made requested changes - since they're all docs changes I haven't updated the CI run.

[emteknetnz]

Broken builds are expected