migration guide

[wsor4035]

WARNING: dumping this here so it doesnt get forgotten(originally discussed on matrix). by no means complete, flushed out. so those of you that want to start drama or complain about something here, just dont - constructive criticism welcome and wanted

like changelog

stuff like:
use core instead of minetest
use string form instead of boolean for use texture alpha
migrate from files mod storage to sqlite
force ztsd for map backend

obviously if stuff like the last two is listed, should be flagged for server owners, or some jazz

example migration guide that comes to mind: https://docs.flutter.dev/release/breaking-changes#released-in-flutter-3-29

[kawogi]

Migration Guide sounds like a super useful thing to have!

Content aside: I think migrations are tightly coupled to the changelog and should not be kept in a separate document. I'd either prefer a dedicated section or enhance the "Deprecations and compatibility notes" section in https://docs.luanti.org/about/changelog/

If this becomes too big, maybe a separate page per version would make sense.

Some questions that might be worth thinking about:

• Who will be looking for a migration guide? (engine devs, modders, server admins, players, ...)
• What's triggering them to search for a migration guide? (bugs, curiosity, awaiting a certain feature, deprecation notices in the logs, recommendation from IRC/Discord/Matrix, ...)
• What's the expected length/format of a typical guide? (a one-liner, command line tool, entire tutorial, video, …)
• What does the reader expect to find? (reasoning behind this change, consequences if not followed, possible alternatives, risks, only the current or also the past migrations, …)

Maybe one can borrow some ideas from the recent Rust language update which covers migration.

I like the idea of flagging/tagging guides w.r.t. the target audience.

[kawogi]

Maybe related: what about migration guides for long-term legacy stuff?

I've seen several code fragments dedicated to transparently handle old configs and file structures. E.g.

		if (can_be_legacy) {
			// If map_meta.txt exists, it is probably a very old world
			if (fs::PathExists(world_path + DIR_DELIM + "map_meta.txt"))
				return LEGACY_GAMEID;
		}

Those cannot easily be assigned to a certain version (and if we did they'd likely be out of sight). If we every want to get rid of these code fragments, users need to have a way to find out that there's something to fix and how to do it. (sorry if this has already been covered somewhere - I didn't do a lot of research).

I could imagine that the migration guides can be linked individually and the logs would refer to them if the engine detects old stuff.