Document the common pitfalls

[kneekoo]

The documentation will likely always lag behind the latest version of the engine, and not everything is thoroughly documented in the first place. But considering that games and mods have various issues related to improper API usage, impacting both players and contributors, a guide covering the most common pitfalls would be very useful.

So instead of sharing empty criticism about how some games and mods are "broken beyond repair", a guide to addressing common issues is the mature thing to do. This helps the entire ecosystem.

[rubenwardy]

here's a start: https://rubenwardy.com/minetest_modding_book/en/quality/common_mistakes.html

[appgurueu]

That's what the [footgun] tag in the issue tracker here would be for.

I'm not sure where we should have a document of "just footguns". The original idea was to just use the appropriate DANGER / WARNING admonitions for docs documenting the relevant features.

[mark-wiemer]

@wsor4035 and team, thoughts on the relevance of this today?

[appgurueu]

Still relevant, most pitfalls haven't really gone away, though some have been alleviated (e.g. privs). Pitfalls generally have to stay because of backwards compatibility (though we can try to offer better alternatives, but then we should also explain why they are better), and especially when copying patterns from legacy code modders may be led to repeat them.

Good API docs will require documenting those.

I think realistically this issue will be open for a good while; documenting pitfalls will always be part of our mission. We could consider codifying this in our mission statement and then closing this issue, instead admitting individual issues for individual pitfalls or collections of pitfalls (such as the one in ruben's book).