Function approval process

[IsmAvatar]

I have a full listing of GM functions and their arguments in LGM:
http://sourceforge.net/apps/trac/lateralgm/browser/LateralGM/trunk/org/lateralgm/jedit/functions.txt
However, this listing does not specify whether the functions are implemented or not.

We also have this list, which was populated courtesy of RetroX:
http://www.enigma-dev.org/docs/Wiki/Remaining_GM_Functions
Although it might be a little tricky to parse due to the variety of information it contains.

[polygone]

I was hoping RetroX would be kind enough to make an implemented list as well as an unimplemented one. It should be easy enough to parse, just check for brackets and it's a function.

[RetroX]

It's just the reverse of what I have for the script.  One second.

EDIT: To get the list, pull the list of keywords, functions, etc. from LGM and shove them into a file named "enig."  Then, copy this file (should be named "gm") and shove it in the same directory.  Run this bash script in that directory to get a list of functions.  Finished functions are prefixed with "FINISHED:", while unfinished ones are prefixed with "UNFINISHED:".

I can update the wiki page if you want, but there's the script if anyone else feels like it.

To get just the unfinished:

Code: [Select]

./list.sh | grep '^UNFINISHED' | sed -r 's/UNFINISHED:[[:space:]]*//'
To get just the finished:

Code: [Select]

./list.sh | grep '^FINISHED' | sed -r 's/FINISHED:[[:space:]]*//'

[polygone]

Will try and bump this topic back up. I'll post useful links for the wiki bot api while I'm here as well, for reference:
http://en.wikipedia.org/w/api.php
http://www.mediawiki.org/wiki/API:Login
http://meta.wikimedia.org/wiki/MediaWiki_Bulk_Page_Creator
http://www.mediawiki.org/wiki/User:Patrick_Nagel/Login_with_snoopy_post-1.15.3

As has been the case for a while everything is ready to go, we just need to write the bot to populate the functions on the wiki.

[TGMG]

I have had an idea for an alternative Function approval process, which will probably save time and be a more efficient way of implementing functions for multiple platforms. The wiki idea would make it difficult to keep track of functions which are implemented differently on multiple platforms. It is also more work for developers who want to try out the functions, have to locate page in wiki, copy/paste it in and write a few tests. Then an enigma developer needs to take all of those functions and commit it into the main svn. It is quite alot of work to get this system running.

I propose a new system based on github and my automatic testing of examples:
I would setup a github repo for enigma for unstable function development, it would contain unimplemented.h which contains all the dummy functions which are either blank or half implemented (some in "#ifdef PLATFORM" blocks which require different implementations per platform).
Anyone who wants to implement a function simply forks the project, implements it fully or makes an attempt at it, then submits a pull request.
This will then get merged into the one repository daily, which anybody and check out to see the latest progress of all the unfinished functions.
The repository will be automatically tested using the 900+ gm examples, which already contain which functions they require so to would just be a case of making sure they work as expected and then the function can be added to the main enigma svn on sourceforge.

This provides a number of benefits, its much easier to make functions which require editing other files, easier to fix bugs, easy to see the progress of all the functions without geting them one by one using the wiki, easy to see how well your game runs based on functions which aren't quite ready, less work editing the wiki, more up to date function lists (easily keep in sync with main svn).

It also keeps the main svn clean for more stable development. Any ideas?

[TheExDeus]

So I see that finally all of the functions are added to the wiki. Now the question is will these pages also serve as the help for the specific function, or will we need to create separate page? Because now I have documented text, sprite and background functions and I want to know if we need these functions separated. One good way would be to keep the currently documented pages, but make function name clickable (thus link each function to its own page). So for example, a user is searching for "Drawing Text", the first page he will hit is this:
http://enigma-dev.org/docs/Wiki/Drawing_text
There he can see all of the drawing functions and also see a short description. Now if he clicks on one of the functions (like draw_text), he will be taken to a separate page:
http://enigma-dev.org/docs/Wiki/Draw_text
Here he could see a longer description, the code used to implement this function, and also examples on how to use this function. This would work great when (or if) LGM allows to open help from the editor. There you would see a search field and the help tree (something like GM's chm), and all of that could be achieved with the wiki.

[polygone]

Yes, that is what I had in mind. Every function will have it's individual page and for function sets/related functions there will be a separate main page outlining the overall system. The main page (in this case http://enigma-dev.org/docs/Wiki/Drawing_text) should be made into a category and all the functions which fall under it should be categorized to it.

Note I haven't yet added the implemented functions to the wiki, only the unimplemented ones. I will be doing those soon, note that if you add a page for any implemented functions before I do the bot will go over them when it's run.

[polygone]

As for this approval process I don't know how it is going to proceed from here.

As the wiki is a lot less frequented than the forum I suggest that a pinned topic should be posted in the peer review forum about the procedure. When writing a new function, a user should post their code in the corresponding wiki function page then make a post in the peer review forum linking to it. Then the function can be discussed on the forum or the wiki page. The user will need to keep the function up to date on the wiki, following the peer review tag system. With function sets/related functions only one post should be made on the forum for discussion.

There is still somewhat of a problem though that without an actual bot in place reporting to the forum, developers are unlikely to notice what new functions have been tagged on the wiki as under review, testing or to commit.

[TheExDeus]

developers are unlikely to notice what new functions have been tagged on the wiki as under review,

They should just visit this from time to time:
http://enigma-dev.org/docs/Wiki/Category:Function:To_Commit
http://enigma-dev.org/docs/Wiki/Category:Function:Testing

[IsmAvatar]

And this:
http://enigma-dev.org/docs/Wiki/Special:RecentChanges

[polygone]

OK to clarify everything. I have run the bot again to put the implemented functions on the wiki.

But the peer review system on the wiki has been abandoned. The functions will now stand there only for documentation. A page has been made on the wiki as a guide to the format the function should ideally be documented with: http://enigma-dev.org/docs/Wiki/Function:Documentation

Note that I am now tagging all functions with either {{Function:GM}} or {{Function:ENIGMA}} so there can be a clear distinction which functions are new to ENIGMA and didn't exist in GM. This then also categorises the functions.

All the functions I have just added to the wiki have been tagged with {{Function:GM}}. However all the ones I ran previously haven't, these are all still using the deprecated {{Unimplemented}}  template tag from the peer review system. So when documenting any of older added functions you should add the {{Function:GM}} tag in yourself.

Also make note that all undocumented functions have been categorised to: http://enigma-dev.org/docs/Wiki/Category:Function:Needs_documenting. With the older added functions I have changed the {{Unimplemented}} tag to categorise the functions there, with the newly added functions I have just added the line [[Category:Function:Needs_documenting]] to categorise them. Thus when you have finished documenting a functions you should remove either the {{Unimplemented}} tag or the [[Category:Function:Needs_documenting]] so they are not categorised as undocumented. In hind-sight I should have probably added another template for the newly added functions instead of using [[Category:Function:Needs_documenting]] or I suppose I could have even just reused the {{Unimplemented}} template again, but too late now 

[polygone]

So now the function peer review process has been removed from the wiki I guess we need another system? There still does not seem to be a consensus though or anyone pushing to implement a particular system.

Maybe, since it really only seems to be the actual developers at the moment doing anything it is not actually worth the effort of making a general peer review system and one would only actually slow things down?

[TGMG]

The easiest way would be for someone to fork my github (https://github.com/amorri40/Enigma-Game-Maker), modify any files required, submit a pull request. The when I get the pull request I will check which games use the functions implemented from here (http://www.alasdairmorrison.com/enigmaexamples/index.php), test the implemented functions in all of the games that require them and if they pass, I will merge the function into main svn. If they fail I will just reject the pull request with a reason.
Very easy to implement this system (its already implemented and ready to go now), very easy to accept and deny new functions, contributors can modify any files they want (add a new platform, bugfix etc) and easy to use (just click the fork button on github).

[polygone]

OK then. How about we just post functions in the peer review forum as normal to be scrutinised, then if anyone notices functions there which seem ready to commit they can submit them to github for testing and to be committed.

[IsmAvatar]

I see nothing wrong with keeping the peer review tags on the wiki, even if they aren't going to be maintained very frequently. As it stands now, functions aren't really implemented at any kind of astonishing rate, and when a function is implemented, it can be marked thusly on the wiki manually, or by a bot if we ever make one. And it's not really a big deal if a function has the wrong tag on it.

Also, people are still welcome to use the wiki to submit functions, they just won't get checked very frequently.

Just because it's progressing slow as molasses (if at all) doesn't mean it's abandoned entirely and useless.