Provide engine documentation

[Zughy]

Problem

TL;DR of There are too many PRs:

• users complaining there are too many issues/PRs
• devs complaining about not having enough dev time
• celeron55 suggesting to contact him if someone wants to become a core dev
• nobody stepping up
• rinse and repeat

Solutions

Provide an engine documentation to give people the possibility to help core devs more easily. Why:

• the code is too vast for any normal human being to understand it in a decent amount of time, meaning...
• if someone's not been here since years, when the code was simpler, can't really do much, meaning...
• old users only can help, IF they didn't lose track of it all, meaning...
• don't expect new core devs, meaning...
• rinsing and repeating the problem

Something similar to the MT modding book would be awesome, for instance explaining the engine hierarchy or acronyms like SAO, CAO, what happens in which etc (the only thing I can find looking for "Minetest CAO SAO" via DuckDuckGo is this)

How about no?

Users will keep increasing, core devs won't. It's like a snowball rolling down the mountain till it becomes an avalanche. Problem: mountain = time, so there's no end to it

Additional context

Current core devs are already doing a lot of work, they can't reproduce theirselves by mitosis nor stop time. Pretending more and more work from them won't work

[ClobberXD]

We do have doxygen support (https://doxygen.minetest.net), but it is currently very under-used. However, I agree that a less code-dependent documentation would be nice. There's also https://dev.minetest.net/Core_Architecture and https://dev.minetest.net/Engine_structure, but both pages are fairly outdated and too basic from what I can tell.

[Zughy]

Yup, last update from 2015. Yet, this scheme is amazing https://dev.minetest.net/images/3/3d/minetest-0.3-dfd-visio.png

[rubenwardy]

I've started to update the documentation, by introducing a landing page: https://dev.minetest.net/Engine

Next, I'm rewriting the Engine Structure page to actually be useful

[Zughy]

@rubenwardy I created a Dev Wiki account to provide translations in Italian. Give a shout when it's done, so I know I can look into it and proceed translating

[paramat]

Zughy,
Your basic request is a good idea of course, but i will correct some misunderstandings:

nobody stepping up

We are always in the process of looking for and inviting new core devs, it is not a case of someone 'stepping up', we invite someone who seems suitable. Someone contacting celeron55 is not how it usually happens.
So be assured the process to add new core devs is always going on, we have been discussing this privately recently. It is an important decision with high requirements, so it does not happen often.

the code is too vast for any normal human being to understand it in a decent amount of time,

This is not how it works, no contributor needs to understand all the code, and most core devs do not either. We all start off understanding and altering small sections, almost anyone can do this.

if someone's not been here since years, when the code was simpler, can't really do much,

old users only can help,

Obviously not true. We have many new contributors.

don't expect new core devs

Obviously not true, core devs are added regularly and that process continues.

Users will keep increasing, core devs won't.

Number of users will not necessarily keep increasing, decreasing is just as likely.

[Zughy]

So be assured the process to add new core devs is always going on, we have been discussing this privately recently. It is an important decision with high requirements, so it does not happen often

I'm genuinely glad to hear that

This is not how it works, no contributor needs to understand all the code, and most core devs do not either

Yes, but you have at least a vague idea of what happens where

Number of users will not necessarily keep increasing, decreasing is just as likely

I have my doubts about that, as Minetest is becoming day by day more "suited" for the general public. Not just the engine, even mods. And I also personally think MT is heading in the right direction, so I hope to not be mistaken

[Zughy]

After two years and some changes in the organisation (we used to have 150 PRs, now we have 80), I guess this is not that necessary anymore - also because the last edit is from ruben, exactly after he commented in here. This means that there is no interest and that new contributors (x2048, TurkeyMcMac etc) understand the code enough to be able to navigate it on their own.

Kind of related, the dev wiki should be completely overhauled and reduced to the bone anyway, as the only useful page right now is probably the meeting one, but this is out of the scope of this issue. Closing