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
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@gmail.comwrote:
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@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise
== 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@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@gmail.comwrote:
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@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
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@gmail.comwrote:
== 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:
- 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
On Tue, Feb 12, 2013 at 9:19 AM, Maria Miteva mariya.miteva@gmail.comwrote:
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@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
Mediawiki-enterprise mailing list Mediawiki-enterprise@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/mediawiki-enterprise
Hi Mariya,
Yes, from my perspective, it's the documentation, and not the changes in the code, that's the bigger issue. Others might have different opinions.
I haven't analyzed the code, but I'm pretty sure the majority of classes and methods don't have a @since tag. Now, I don't know if it would be a good use of anyone's time to go back and add @since tags to every public class and method (though then again, maybe it would be), but it would be nice for developers to try to make sure to always do it going forward. Some do it already, which is good.
-Yaron
On Thu, Feb 14, 2013 at 7:26 AM, Maria Miteva mariya.miteva@gmail.comwrote:
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
mediawiki-enterprise@lists.wikimedia.org