Mark record_migrations as legacy in the docs

[hyanwong]

And suggest using additional_nodes=msprime.NodeType.MIGRANT on its own.

See tskit-dev/tskit#3348 (comment)

I think record_migrations is mainly mentioned in https://tskit.dev/msprime/docs/stable/ancestry.html#migration-events

I'm happy to assign myself to this.

[jeromekelleher]

We should take care to go through the examples of using migration records to show how to translate. This would be a good thing to do before marking it as deprecated, so that we can be sure that they are genuinely redundant now.

I guess a phased plan would be to start raising a deprecation warning in msprime in an upcoming release (assuming we have some documentation to point to discussing this, including examples of how to translate code using migration records), then remove the option in a subsequent release of msprime, then remove it from tskit. This would undoubtedly break a bunch of stuff downstream like tszip, etc, so there would be a significant blast radius.

So: this a major undertaking which we should not set in motion unless we are serious about putting the extensive drudge work into. This is not just a case of doing a few documentation PRs and walking away, so please don't set this in motion unless you personally are prepared to do the leg work.