Write migrations for each release

[kchibisov]

We should write migrations between releases showing who to port certain code and probably linking to discussions why certain change were made in the first.

Then e.g. rustdoc/CHANGELOG could link to relevant entries for migrations.

An example for such migration is like that:

#3447 (comment)

The migrations should probably in migrations directory with format migration_release.md(only for major releases with breaking changes).

[madsmtm]

I think the changelog is the place to put migrations, as they're only really relevant for that particular release, and only relevant when you're upgrading.

[kchibisov]

Maybe we should just make CHANGELOG per release? Like my main issue is that I don't really want a giant file with all of that, since it'll only grow over time.

[madsmtm]

I think it's fine that it grows, that's how changelogs are, and it is kinda convenient to be able to go back in history in it. It's like a poor mans git blame.

[kchibisov]

The issue starts when you include code snippets there. oneliners are fine, so that's why I'd rather maintain separate entries for migrations itself.

[daxpedda]

I would also prefer one big file.

[notgull]

Seconding @madsmtm and @daxpedda. This seems like the point of the CHANGELOG. If we format it better it should be useful for this purpose.

[kchibisov]

I don't see why putting separate changelog for each release won't work as in the current CHANGELOG.md represents the next release, the rest is just stashed inside the changelogs, so we have something that can be nicely rendered on docs.rs without bringing the entire winit lore.

Like I don't want to maintain 10K lines of markdown.

[madsmtm]

We discussed this in today's meeting, the conclusion was to split changelog per major version into files and include migrations into each file. Docs.rs integration would also work well with this.

I've assigned myself on the issue, as I'll attempt to put up a PR for this.

Unresolved is whether or not to backport this to v0.29, I guess it depends on whatever @kchibisov thinks is easiest.

[madsmtm]

Will close this once we have written the migrations for 0.30

[madsmtm]

#3612 or #3614 will resolve this, we'll need to do some work to merge these two PRs though.