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 <katkov.juriy(a)gmail.com>wrote;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 <yaron(a)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
On Tue, Feb 12, 2013 at 9:19 AM, Maria Miteva <mariya.miteva(a)gmail.com>wrote;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
Mediawiki-enterprise(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise
--
WikiWorks · MediaWiki Consulting ·
http://wikiworks.com
_______________________________________________
Mediawiki-enterprise mailing list
Mediawiki-enterprise(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise
_______________________________________________
Mediawiki-enterprise mailing list
Mediawiki-enterprise(a)lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise