Hi, Thank you for the replies. I guess I keep understanding this wrong.. So for what I understand, the problem is not that much in the frequent changes in hooks and classes. etc. MediaWiki seems to be doing a good job with that?
Tha problem seems to be in documnting how things should be done, what each class does in detail, and since when and until when a class has been and will be active. Do I understand correctly now? Are there examples of classes which : * don't have a good enough description? * are not marked with @since other than WikiPage? Or is this the majority? * have been deprecated without warning? * changed witout warning? Regards, Mariya On Tue, Feb 12, 2013 at 11:09 PM, Yury Katkov <[email protected]>wrote: > == 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. > > Another thing is that the is not much programming documentation, like it > is in Drupal for example: > http://drupal.org/documentation/customization/tutorials/beginners-cookbook > > > 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 <[email protected]> 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 >> >> On Tue, Feb 12, 2013 at 9:19 AM, Maria Miteva <[email protected]>wrote: >> >>> 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. >>> >>> http://www.gossamer-threads.com/lists/wiki/wikitech/267106 >>> >>> 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 >>> [email protected] >>> https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise >>> >>> >> >> >> -- >> WikiWorks · MediaWiki Consulting · http://wikiworks.com >> >> _______________________________________________ >> Mediawiki-enterprise mailing list >> [email protected] >> https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise >> >> > > _______________________________________________ > Mediawiki-enterprise mailing list > [email protected] > https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise > >
_______________________________________________ Mediawiki-enterprise mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise
