Mention the Media.merge change in the release notes

[Matthias Kestenholz]

The Media merge change (#30179, #30153) has some potential of breaking libraries which worked before. It would be nice to give a heads-up to developers that they have to check their Media definitions.

The necessary change to django-content-editor was really small: ​https://github.com/matthiask/django-content-editor/commit/ed662db302fd74033ce62031bb11b6f8beddf249

Here's a draft for the release notes (I hope it helps -- I'm finding it hard to keep it short while still providing an useful example)

--

Merging of media classes

The Media class merging algorithm has been changed to produce sensible results when pairwise merging is insufficient. However, CSS and JavaScript files which do not properly declare their dependencies may now be reordered before their dependencies. This only ever worked by accident.

The recommendation is to check all Media declarations for dependencies and make those explicit. Just as an example, widgets depending on django.jQuery should specify js=["admin/js/jquery.init.js", ...]

[Carlton Gibson]

Hey Joe. Yep, fine. Do you want to make that PR? (I can do it quickly if you say no.)

[Matthias Kestenholz]

Hey, that was me :)

I'd appreciate it if you did the PR. I just thought I'd cc Johannes because of his involvement.

[Johannes Maron]

Hi @Matthias,

thanks for letting us know about this. I believe it's a good idea to add some documentation here. Since other might rely on implicit dependencies especially with the old merging warning.

Since you encountered the issue, what would you suggest as documentation. What would have helped or pointed you into the right direction?

Best,
Joe

[Carlton Gibson]

Sorry. I misread the UI. I'll make a PR this PM. Thanks both.

[Matthias Kestenholz]

Thanks, both of you.

I'd add the sentence in the ticket description under the "forms" heading and also mention the change under the "admin" heading, coupled with the recommendation of adding jquery.init.js to the js list.

(It didn't confuse me this time since I authored the last change to Media.merge. A hint with what-to-do / upgrading instructions would be very helpful though. Upgrading instructions for breaking changes is a thing I missed in the past, e.g. when get_query_set was changed to get_queryset etc.)

[Carlton Gibson]

​PR with ≈suggestion from Matthias.

[GitHub <noreply@…>]

In 418263c4:

Fixed #30263 -- Doc'd changes to form Media sorting (refs #30179).

Thanks to Tim Graham for review.

[Carlton Gibson <carlton.gibson@…>]

In 19ab6989:

[2.2.x] Fixed #30263 -- Doc'd changes to form Media sorting (refs #30179).

Thanks to Tim Graham for review.
Backport of 418263c457636d3301f2068c47f09a0f42e15c52 from master