Deprecated functions, Dev Wiki, and warnings.

User avatar
Hamlet
Member
 
Posts: 558
Joined: Sat Jul 29, 2017 21:09
Location: Lombardy, Italy
GitHub: h4ml3t
IRC: H4mlet

Deprecated functions, Dev Wiki, and warnings.

by Hamlet » Wed May 30, 2018 12:08

For example:

According to the Dev Wiki to read a minetest.conf's setting you have to:

minetest.setting_getbool("name")

Recently I've discovered that it is a deprecated method, and you have to:

minetest.settings:get_bool("name")

Minetest 0.4.16 doesn't raise any warning about it, so I guess that either method is valid - for now.
Will 0.4.17 raise warnings? I think it should, to let developers know that they should update their code.

I'm using the Dev Wiki on a daily basis, because it contains examples and explanations that make it easier to understand than Minetest's lua_api.txt.
Would it be possible to add an header on those pages to warn its readers to refer to the lua_api.txt for the up to date methods?
This way it would be clear that the example code is to be considered as something to refer to for learning purposes, but that the actual implementation should be done checking the most updated API reference text.
SelfNote: "KeepCalm, Remember that Ppl also HaveRealLife stuff to do. PS bite your tongue, just in case."
 

User avatar
Pyrollo
Member
 
Posts: 316
Joined: Mon Jan 08, 2018 15:14
Location: Paris
GitHub: pyrollo
In-game: Naj

Re: Deprecated functions, Dev Wiki, and warnings.

by Pyrollo » Wed May 30, 2018 12:53

The dev wiki is maintained by developpers like you and me.

Best thing to do when you find out such outdated information is to update the wiki according to the lua_api.txt (which is the reference documentation).

I often take a few minutes to do that when I discover new features or changing stuff in lua_api.txt that is not in the wiki.
[ Display Modpack ] - [ Digiterms ] - [ Crater MG ] - [ LATE ]
 

User avatar
Linuxdirk
Member
 
Posts: 2177
Joined: Wed Sep 17, 2014 11:21
Location: Germany
In-game: Linuxdirk

Re: Deprecated functions, Dev Wiki, and warnings.

by Linuxdirk » Wed May 30, 2018 15:33

Pyrollo wrote:The dev wiki is maintained by developpers like you and me.

Image

The problem with the wiki is, that it is outdated and incomplete. And the deeper you dig into modding the more outdated or outright missing (finding a and b took me 5 seconds) stuff you stumble upon.

For widely used things that do not change often, like node registration the wiki might work, but that’s it. For anything above that better u se the lua_api.txt file.

The best would be ditching the wiki completely and rely to the already existing API documentation but since the wiki is one/some of the dev’s pet projects this won’t happen.
 

twoelk
Member
 
Posts: 1324
Joined: Fri Apr 19, 2013 16:19
Location: northern Germany
GitHub: twoelk
IRC: twoelk
In-game: twoelk

Re: Deprecated functions, Dev Wiki, and warnings.

by twoelk » Wed May 30, 2018 15:36

Hamlet wrote:Recently I've discovered that it is a deprecated method, and you have to...
...
I'm using the Dev Wiki on a daily basis, because it contains examples and explanations that make it easier to understand than Minetest's lua_api.txt.
Would it be possible to add an header on those pages to warn its readers to refer to the lua_api.txt for the up to date methods?
This way it would be clear that the example code is to be considered as something to refer to for learning purposes, but that the actual implementation should be done checking the most updated API reference text.

Pyrollo wrote:The dev wiki is maintained by developpers like you and me.


Absolutely nobody is officially assigned to the job of keeping the dev-wiki or the generall minetest-wiki up-to date.

Anybody who feels like it may work on the wiki. If you find anything missing or outright wrong please please please change or add it to the wikis. Both wikis dearly need the help of more people to do more of the boring maintenance jobs like updating lots of pages when things change in minetest versions.

So don't complain that somebody is not doing his job - it's a wiki! - if you notice something that ought to be done then by all means it is indeed your job to do it.

Adding a label that a page is outdated is waisted time in my opinion. Instead bring the information up to date and if there is historical value put the outdated data into some chapter about past versions, best with date or version of change if possible as this may help others to pin down similar issues.
 

User avatar
Linuxdirk
Member
 
Posts: 2177
Joined: Wed Sep 17, 2014 11:21
Location: Germany
In-game: Linuxdirk

Re: Deprecated functions, Dev Wiki, and warnings.

by Linuxdirk » Wed May 30, 2018 16:34

twoelk wrote:So don't complain that somebody is not doing his job - it's a wiki! - if you notice something that ought to be done then by all means it is indeed your job to do it.

If I’m in the middle of coding a mod I’m not going to add missing information to the wiki but go to the official API documentation because I want to know something, and not to teach something.
 

User avatar
Hamlet
Member
 
Posts: 558
Joined: Sat Jul 29, 2017 21:09
Location: Lombardy, Italy
GitHub: h4ml3t
IRC: H4mlet

Re: Deprecated functions, Dev Wiki, and warnings.

by Hamlet » Wed May 30, 2018 21:56

I haven't been clear: I am not suggesting to add a warning header to the outdated pages instead of updating them - that would be a nonsense: I am suggesting to add an header displayed on ALL the Dev Wiki's pages.

Dear developer, these are just code examples that may be outdated due to the wiki's nature, please always refer to lua_api.txt for the up-to-date methods.
If you would like to help mantaining this wiki <ask here link>, thanks!


I know that like any other wiki, it is mantained by volunteers, thus it is natural that something isn't updated. The page I've used for the example is five years old, the main page itself is three years old. No complaints here, don't get me wrong: it would be crazy to expect that a person (or a few persons) can possibly handle all those pages alone.

The Dev Wiki is good, helpful and rich; some have the time to work on it (thank you!) some don't.
So let's keep it like it is, but let's just add a suggestion to always refer to the API texts (../minetest/doc/ and/or ../minetest_game/game_api.txt), simple and easy.
SelfNote: "KeepCalm, Remember that Ppl also HaveRealLife stuff to do. PS bite your tongue, just in case."
 

twoelk
Member
 
Posts: 1324
Joined: Fri Apr 19, 2013 16:19
Location: northern Germany
GitHub: twoelk
IRC: twoelk
In-game: twoelk
 

User avatar
Pyrollo
Member
 
Posts: 316
Joined: Mon Jan 08, 2018 15:14
Location: Paris
GitHub: pyrollo
In-game: Naj

Re: Deprecated functions, Dev Wiki, and warnings.

by Pyrollo » Thu May 31, 2018 07:57

Linuxdirk wrote:The problem with the wiki is, that it is outdated and incomplete. And the deeper you dig into modding the more outdated or outright missing (finding a and b took me 5 seconds) stuff you stumble upon.

For widely used things that do not change often, like node registration the wiki might work, but that’s it. For anything above that better u se the lua_api.txt file.

The best would be ditching the wiki completely and rely to the already existing API documentation but since the wiki is one/some of the dev’s pet projects this won’t happen.


Sorry if I'm a bit harsh but it would have taken less time to create that missing wiki page from lua_api.txt than to write this message on the forum.

Of course, when we are developping, we do not want to stop to do something else. But we can update the wiki later according to our findings. I would say, it's the same thing for posting on this forum.
[ Display Modpack ] - [ Digiterms ] - [ Crater MG ] - [ LATE ]
 

User avatar
Hamlet
Member
 
Posts: 558
Joined: Sat Jul 29, 2017 21:09
Location: Lombardy, Italy
GitHub: h4ml3t
IRC: H4mlet

Re: Deprecated functions, Dev Wiki, and warnings.

by Hamlet » Thu May 31, 2018 09:31

twoelk wrote:


no offence intended but it just fits so well I couldn't resist


Google translator:
"Blame the world for what it is
It would only be your fault if she stays that way"

No offence taken, however what you just did is to "put words in (one's) mouth": "Fig. to interpret what someone said so that the words mean what you want and not what the speaker wanted."
https://idioms.thefreedictionary.com/put+words+in+mouth

Despite my last post, where I have clarified beyond any reasonable doubt what I meant when I've started this thread. My first and second post are meant to help the community suggesting a solution, not to criticize someone or something.
I am starting to doubt that anyone has actually read them. Or maybe I am speaking Greek.
(https://en.wikipedia.org/wiki/Greek_to_me)

If this thread has to be hijacked to be used as an argument against this or that person, which is, arguing for the sole pleasure of arguing against something or someone - then let's stop it here and now, speaking of wasted time.
SelfNote: "KeepCalm, Remember that Ppl also HaveRealLife stuff to do. PS bite your tongue, just in case."
 

twoelk
Member
 
Posts: 1324
Joined: Fri Apr 19, 2013 16:19
Location: northern Germany
GitHub: twoelk
IRC: twoelk
In-game: twoelk

Re: Deprecated functions, Dev Wiki, and warnings.

by twoelk » Thu May 31, 2018 12:02

er, rather:
it is not your fault that the world is as it is
but it would be your fault if it stays as it is


and I admit it was rather coined at Linuxdirk whom I presume to understand the german version and will probably know the linked song. (btw the video pictures are great fun but have pretty much nothing to do with the lyrics)

I draw building plans in real life and usually add to every drawing an info text allong the lines of: "no quarantee is given that the plans are absolutely correct. Every measurement must be checked on the actually built construction." Similar warnings probably exist for most fields of working in real life. So I guess a small warning on each page could be considered ...
but then again ...
it's an open wiki !
do people really expect a wiki to be the absolute and final truth?

so yeah, maybe every open wiki should contain a warning such as:
"Beware this is open content, anybody can write or change it at any time. Please double check any facts before using them."

the most important thing though is please help make the wiki better.
and yes this does also go at Linuxdirk and many others <sarcasm alert> who do complain a lot about lazy devs that selfishly only work on things they themselves consider important while the devs should rather in their opinion serve the general minetest modder or player.</sarcasm alert> The complainers often have good insights and sometimes even spill important information they stumble over but they don't really seem to like adding it to places where the minetest community tries to collect such information in an organized way.
 

User avatar
Hamlet
Member
 
Posts: 558
Joined: Sat Jul 29, 2017 21:09
Location: Lombardy, Italy
GitHub: h4ml3t
IRC: H4mlet

Re: Deprecated functions, Dev Wiki, and warnings.

by Hamlet » Thu May 31, 2018 19:11

Got it, thanks for clarifying. :)
SelfNote: "KeepCalm, Remember that Ppl also HaveRealLife stuff to do. PS bite your tongue, just in case."
 

User avatar
Linuxdirk
Member
 
Posts: 2177
Joined: Wed Sep 17, 2014 11:21
Location: Germany
In-game: Linuxdirk

Re: Deprecated functions, Dev Wiki, and warnings.

by Linuxdirk » Thu May 31, 2018 19:38

twoelk wrote:The complainers often have good insights and sometimes even spill important information they stumble over but they don't really seem to like adding it to places where the minetest community tries to collect such information in an organized way.

The biggest problem with the developer wiki is: WHY? Devs (MT devs and mod devs alike) already have the code and the official API documentation for research. Those are already in one place and organized.

There is nothing wrong with a “normal player wiki”. But why should devs use and maintain a redundant source of information that has to be edited manually?

So either use a bot to fill the wiki automatically by parsing the API documentation (there already is a GitHub issue for that … in a way) or ditch the dev wiki completely and refer to the API documentation only.
 

User avatar
pandaro
Member
 
Posts: 320
Joined: Sun Jan 08, 2012 21:34
Location: behind
GitHub: pandaro

Re: Deprecated functions, Dev Wiki, and warnings.

by pandaro » Thu May 31, 2018 19:52

I suggest that contributors to the wiki are also highlighted in the forum as a "wiki maintainer".
Perhaps some would be more motivated.
 

User avatar
Pyrollo
Member
 
Posts: 316
Joined: Mon Jan 08, 2018 15:14
Location: Paris
GitHub: pyrollo
In-game: Naj

Re: Deprecated functions, Dev Wiki, and warnings.

by Pyrollo » Fri Jun 01, 2018 07:57

Linuxdirk wrote:There is nothing wrong with a “normal player wiki”. But why should devs use and maintain a redundant source of information that has to be edited manually?
So either use a bot to fill the wiki automatically by parsing the API documentation (there already is a GitHub issue for that … in a way) or ditch the dev wiki completely and refer to the API documentation only.


I agree with the redundance. But for me, there are at least two good reasons of having a dev wiki :

- Thanks to text formatting, it is easier to read than lua_api.txt;
- We can have extra information that should not be in lua_api.txt. For example this page : http://dev.minetest.net/Mapgen_memory_optimisations

The wiki could be even better if it adds more code examples and tips. But yes, we have to find a way to deal with outdated information.
[ Display Modpack ] - [ Digiterms ] - [ Crater MG ] - [ LATE ]
 

User avatar
Wuzzy
Member
 
Posts: 3610
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy

Re: Deprecated functions, Dev Wiki, and warnings.

by Wuzzy » Sat Jun 02, 2018 21:57

WARNING: The dev wiki is NOT official documentation, never was. But it looks like one. This is very bad and must change. Only lua_api.txt is official.

The ONLY logical step is to delete ALL pages on the Dev Wiki concerning about particular functions, i.e. stuff already explained in lua_api.txt. The reason is that they are just pointlessly redundant and inconsistent with official documentation. This is harmful because modders might be fooled in thinking they are reading official documentation.

I disagree with deleting the Dev Wiki entirely. What can stay are supplemental information, developer hints, list of intereting tools, tips and tricks, code examples, and the like. But not a duplication of lua_api.txt.

- Thanks to text formatting, it is easier to read than lua_api.txt;

I don't care, it's redundant. Lua_api.txt just needs a proper rendering, that's all.

Here's one:
https://rubenwardy.com/minetest_modding ... a_api.html
My creations. I gladly accept bitcoins: 17fsUywHxeMHKG41UFfu34F1rAxZcrVoqH
 

User avatar
domtron vox
Member
 
Posts: 111
Joined: Thu Feb 20, 2014 21:07
GitHub: DomtronVox
IRC: Domtron
In-game: Domtron

Re: Deprecated functions, Dev Wiki, and warnings.

by domtron vox » Sun Jun 03, 2018 01:00

Just my two cents about this topic.

I tried working on the wikis several years ago and eventually gave up. Mostly I was confused what went in which wiki.

I guess the Dev wiki should hold data for core developers and anyone extending the engine while the General wiki holds minetest history, info on different mods and games, and modding tutorials/help.

Also I'm wondering if we should replace the dev wiki with something like what OpenClonk does for documentation (https://docs.openclonk.org/en/sdk/) then try to generate as much of it as possible with automated builds along side some manual documentation.
 

User avatar
rubenwardy
Moderator
 
Posts: 5835
Joined: Tue Jun 12, 2012 18:11
Location: United Kingdom
GitHub: rubenwardy
IRC: rubenwardy
In-game: rubenwardy

Re: Deprecated functions, Dev Wiki, and warnings.

by rubenwardy » Sun Jun 03, 2018 01:28

Dev is for developers, so modding, game, and engine dev

Wiki is for players, so help with certain mods and games, configuration help, etc
 


Return to General Discussion



Who is online

Users browsing this forum: No registered users and 8 guests