== About the documentation ==
For the novice developers the biggest issue is that they don't know which way is the right way to do things in MediaWiki. Very often the methods are marked as deprecated but contain no comments of how to do it.
There the documentation is grouped by your use case: "creating menus", "tuning appearance of the nodes". In MediaWiki there is a lot of hooks which make the system relatively simple and extensible, but not many examples and tutorials like:
- how to tune the History page? The Recent Changes?
- how to replace the Edit page?
- How to use the information about the user?
- how to properly create tables?
- how to customize the toolbox, the editbox, the search?
- how to work with revisions?
- how can we affect the work of the parser?
The answers now can be found in the code of existing extensions but that slows the process of learning the system.
== About the PHP API ==
MediaWiki Internal API consists the following parts:
1) Hooks. They are sacred! The hook deprecation policy must be very slow, maybe three versions long
2) Public classes. Parser class in public but Preprocessor_Hash is probably not.
There are classes that are recommended to use by the extension developers. They're grouped in modules: api, db, cache, media etc. Currently there is no description of these classes and modules except those in PHPDoc. Here is an example of module description in Qt library:
http://qt-project.org/doc/qt-5.0/qtwidgets/qtwidgets-index.html And here is the detailed description of one of their public classes:
http://qt-project.org/doc/qt-5.0/qtwidgets/qcalendarwidget.html#details . It contains the instructions of how to use this class and how it is linked with other classes. During my 2 years of using Qt library I've seen their sources just three or four times. That's what can be called the documented system.
Every single method of public class has to have the PHPDoc. Removing the methods or fields from the public class have to be relatively slow.
3) js stuff. Resource Loader guys have done good job of documenting the loader here.
-----
Yury Katkov, WikiVote
On Wed, Feb 13, 2013 at 12:31 AM, Yaron Koren
<yaron@wikiworks.com> wrote:
Hi Mariya,
I've been dealing with changes to MediaWiki core pretty much since I started doing extension development, six years and 12 versions ago. In my experience, the deprecation of methods is actually not that big an issue - even if methods or functions aren't correctly tagged as being deprecated, or they go away too soon, it's still not a big deal, because as long as you run your extensions' code regularly against the latest MediaWiki code, you can see what the issues are and have enough time to fix them before the next version is officially released. Also, there are a number of core developers who go through all the extension code in the repository and replace calls to deprecated methods, which is very helpful.
In my opinion, the bigger issue is that code should more frequently be tagged with "@since", so that we can more easily provide *backwards* compatibility. I try to have my extensions support all MediaWiki versions from the previous two years, if possible. Just today, I was trying to figure out when the class WikiPage got its start, so that I could know whether I could assume it was there. There was no top-level @since tag, so I had to go through its page history in Gerrit, which took a while to load, to find the answer (MediaWiki 1.18). Ideally, there should have been a "@since 1.18" right above the class declaration. I know it's a pain to add @since everywhere, but it really is helpful to extension developers.
-Yaron
Hi all,
I have heard from some of you that it would be very helpful to have some stability in the exposed classes/methods of MediaWiki core for extension development and to look at MediaWiki as a programming interface. I raised this as an issue with the developer community and was told that this has been a priority since version 1.18 and the following email by Daniel.
I was wondering if you could provide similar examples of issues you have faced where methods have been removed without warning and deprecation or any other unexpected changes, which have affected your upgrades and the extensions you use since then. It has only been two major releases since then, so maybe the problem has actually been solved to a great extend but people have not been able to feel it much yet. Are you still experiencing such problems?
Mariya
Mediawiki-enterprise mailing list
Mediawiki-enterprise@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise
--
WikiWorks · MediaWiki Consulting · http://wikiworks.com
_______________________________________________
Mediawiki-enterprise mailing list
Mediawiki-enterprise@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise