Migration guide for old users of xarray-contrib/datatree

[flamingbear]

What is your issue?

This is an Issue to keep track of changes that have been made to DataTree from the initial migration of the code in xarray-contrib/datatree

[welcome]

Thanks for opening your first issue here at xarray! Be sure to follow the issue template!
If you have an idea for a solution, we would really welcome a Pull Request with proposed changes.
See the Contributing Guide for more.
It may take us a while to respond here, but we really value your contribution. Contributors like you help make xarray better.
Thank you!

[flamingbear]

Wasn't positive if I wanted to have a block in the actual top level issue or let people just add comments for the breaking changes.

[flamingbear]

- ``Datatree``'s ``as_array`` renamed ``to_dataarray`` to align with ``Dataset``. (:pull:`8789`)
  By `Owen Littlejohns <https://github.com/owenlittlejohns>`_ and `Matt Savoie
  <https://github.com/flamingbear>`_

[TomNicholas]

Everything in #9297

[TomNicholas]

We should take this list and use it to write a short migration guide for all the intrepid users of the original xarray-contrib/datatree package.

I'm not sure where the guide should live - it's not relevant for general xarray users who will use the version in main as their first experience of DataTree, and at some point hopefully it will become irrelevant as every user of xarray-contrib/datatree will have migrated. So it perhaps shouldn't live in the main xarray docs?

It also will become out of date as soon as we make any more backwards-incompatible changes to the new version of datatree. I don't think we need to go back and update the document - it describes differences at a specific point in time, and we have a whats-new for any further changes.

So perhaps we should just stick it on the old repository?