Separating skins from core MediaWiki


 * Public URL: https://www.mediawiki.org/wiki/Separating_skins_from_core_MediaWiki
 * Bugzilla report
 * Core skins should initialise and include like other skins/extensions do
 * Unified approach for skin extensions


 * Announcement: http://lists.wikimedia.org/pipermail/wikitech-l/2014-March/075395.html
 * Abstract: I intend to separate core skins out of MediaWiki, removing cross-dependencies with MediaWiki itself, and making it possible for non-core skins to have all of the capabilities of core ones. As a prerequisite, I wish to simplify the skin creation, packaging and (un)installation. This would make the lives of both skin creators and site administrators wishing to use a non-default skin a lot easier. If everything goes well, the core skins will be moved out of core, to separate git repositories.

This is an accepted Google Summer of Code 2014 proposal.

Name and contact information

 * Name: Bartosz Dziewoński
 * Email: matma.rex@gmail.com
 * IRC or IM networks/handle(s):
 * freenode IRC: MatmaRex
 * XMPP: matma.rex@gmail.com


 * Web Page / Blog / Microblog / Portfolio: https://github.com/MatmaRex
 * Location: Poland
 * Typical working hours: afternoons and evenings CEST

Synopsis
MediaWiki core includes four skins, and allows site administrators to create and install additional ones. However, the process is less than pleasant, due to several related problems (lack of documentation, more than one "correct" way to make a skin work, directory layout that makes packaging and (un)installation difficult, core skins and MediaWiki itself being interdependent, and possibly others).

I intend to solve at least two of the aforementioned issues by devising and documenting a saner directory layout for skins (and applying it to the four core ones) and then carefully disentangling them from MediaWiki code, removing cross-dependencies and making it possible for non-core skins to have the same level of control over all aspects of the look&feel as core ones currently have. This would make the lives of both skin creators and site administrators wishing to use a non-default skin a lot easier.

If everything goes well, the process would be culminated with moving the core skins out of core, to separate git repositories. This would require coordination with MediaWiki release managers (to have them shipped in the release tarballs the way certain extensions are shipped now) and Wikimedia Foundation Operations team members (to ensure the deployment of the new system on Wikimedia wikis goes smoothly), so it cannot be made a part of my core proposal.


 * Mentors
 * Jon Robson
 * Ori Livneh

Deliverables
To avoid any confusion among both laypeople and developers, let's first state that I will not be creating any new skins, nor rewriting the  and   classes.

Stage 1: Improve skinning mechanisms ()
Define and document a standard, recommended way to create skins, after investigating the ways that are currently used.

I'm currently leaning towards a structure similar to the one used by extensions, but with the skins themselves staying in the  directory. This would either use an autodiscovery mechanism to make skins instantly available (similar to what MediaWiki does already) or require users to add an entry to  (similar to what extensions do already).


 * Document the expected directory layout. ✅, documented at.
 * Document how to define ResourceLoader modules and use them in the skin, making them work both in production and debug mode. ✅, documented at.
 * Create an example skin following the best practices. A husk with sane HTML structure and basic styles, that can be used as a starting point by lazy skin creators. ✅, see Skin:Example, code available in the mediawiki/skins/Example repository.
 * (optional) Create a tutorial on this., the expanded is more than sufficient.
 * (optional) Encourage using the same HTML structure in new skins (but do not enforce it). Writing skins that would be compatible with existing scripts and scripts that would be compatible with a wide variety of skins would be easier if everyone stuck to the same conventions. ❌
 * (optional) Convert at least one existing skin to new standard. ✅ Modern, Cologne Blue, Nostalgia.
 * (optional) Document the process of such conversion. I believe it will be straightforward enough that some examples will suffice. ✅, documented at Manual:Skin autodiscovery.

Make it easier to install and manage skins.


 * Consider deprecating current autodiscovery mechanism, with  file and   directory, in favor of the new system. It makes it unpleasant to add or remove skins, makes it hard to add skins to .gitignore. ✅: discussed, documented and deprecated (see Manual:Skin autodiscovery).
 * (optional) Investigate widely used non-core skins and ensure they will stay compatible with newer MediaWiki versions.
 * Provide support for enabling or disabling skins in the MediaWiki installer. Reusing the way it currently handles extensions should be relatively straightforward. ✅, implemented in Support for enabling skins in the installer patch. Further improvements (like providing screenshots for each skin or actually previewing them live) tracked as blocked by.

Make skins more powerful.


 * Provide a way for skins to add styles to core/extensions' ResourceLoader modules. This would be a hard prerequisite for stage 2, as core skins currently abuse core mechanisms to do this. ✅, patch: Allow skins to provide additional styles for any module.
 * Consider deprecating, which allows the inverse: for modules to define styles only applied to certain skins. MediaWiki uses this heavily for core skins. ✅, considered and not deprecated after all: both approaches have their use cases.
 * (optional) Provide a way for skins to interface with MediaWiki client-side. I might lay some foundations to this, but creating an entire, complete system might be a task for a few months by itself. ❌, this is one of the facets of the "Redo skin framework" RFC and it's better to let that happen.
 * Allow skins to define methods for common UI operations (overriding default best-guess ones). Currently several core modules make some heavy-handed assumptions about skins' HTML structure to achieve some degree of compatibility. This includes, among others, AJAX watchlisting, adding navigation links (tabs, sidebar), showing notifications, defining the element that is the content wrapper…

Stage 2: Separate core skins from MediaWiki itself ()
This includes Vector (the default skin), MonoBook, Modern and CologneBlue.

Identify and get rid of places where MediaWiki code is mixed with skin-specific code.


 * The basics: localisation messages, ResourceLoader modules, autoloader class definitions… ✅.
 * Audit all of core's CSS and JavaScript, remove anything skin-dependent., a brief audit has shown that this is a lesser issue than I anticipated and so I focused on other areas of this project.
 * If necessary in order to preserve functionality, create interfaces (broadly speaking) allowing the skin and MediaWiki to cooperate: hooks (server- or client-side), well-defined CSS classes, helper methods.
 * Audit major extensions and do the same. Two extensions that would definitely benefit from this are VisualEditor and Echo, there may be more.

(optional) Move all four core skins to separate repositories.

The separated skins would have to be bundled with the tarball, and would require some new process to be deployed and updated on Wikimedia servers. I have not investigated either of these in detail yet, but it seems like the solutions for handling extensions should be easy to reuse. I am hoping for some help from (respectively) the MediaWiki release managers and Wikimedia Foundation Operations team.

I marked this as 'optional' due to the caveats above, but I am really really hoping to complete this step. The project would nevertheless be beneficial to MediaWiki without it, but it would feel "incomplete" to me.

This would come with several benefits:
 * Being able to change what we ship with the tarball more easily. In the future (I'm just dreaming now, this is out of scope of this particular project) we might add some new pretty skins and maybe remove some of the default four which have been a bit neglected (but still make them available). Currently doing that would require migrating a lot of code between repositories and modifying it to match core conventions – with everything separated properly no code changes should be necessary.
 * More focus on keeping core code compatible with all skins. It will be clear that one might not make MediaWiki core depend on the layout of a particular skin.

If this is done, MediaWiki would require a tiny fallback skin (for situations when no regular skins are installed). It would show just the page content and basic navigation ( allows one to build it easily) with none or minimal styles, and a big message suggesting installing some skins.


 * ✅ Modern and Cologne Blue, and then Vector and MonoBook, have all been moved to separate repositories and core MediaWiki no longer depends on them.
 * ✅ Fallback skin has been implemented, patch: Use a special fallback skin when selected skin is unavailable.
 * ✅ The Wikimedia deployment process has been worked out, the changes are live on beta and will be deployed in production by the end of August.
 * ❌ Tarball packaging process has not been updated during this project. The work is being tracked at and I will continue working with MediaWiki release managers on it.
 * ❌ Tarball packaging process has not been updated during this project. The work is being tracked at and I will continue working with MediaWiki release managers on it.

Timeline
See "Deliverables" above for an extended plan for each step.


 * Stage 1
 * 2014-05-20 – 2014-06-03: Define and document a standard, recommended way to create skins, after investigating the ways that are currently used.
 * 2014-06-04 – 2014-06-10: Make it easier to install and manage skins.
 * 2014-06-11 – 2014-06-23: Make skins more powerful.


 * Stage 2
 * 2014-06-30 – 2014-07-21: Identify and get rid of places where MediaWiki code is mixed with skin-specific code.
 * 2014-07-22 – 2014-08-11: Move all four core skins to separate repositories.

Participation
I am going to push new commits to a separate topic branch on Gerrit to make them open for review from anyone interested. Hopefully my changes are going to be merged on a regular basis, but if that proves impossible I am going to manage the dependencies between the commits I submit.

I'll update the wikitech-l mailing list with information about milestones being reached. If I decide that something needs public consultation, I will also use the list, as well as Bugzilla. I'll also usually be available on #mediawiki and #wikimedia-dev on freenode (during afternoons and evenings CEST).

About you
I am a Polish Wikipedia editor, administrator and bureaucrat, where I usually deal with all of the technical aspects of the project. I contribute to the MediaWiki software as well, for a little more than a year now; I have fixed a number of bugs and completed a few smaller or larger projects. (Most significant ones would probably be a rewrite of the CologneBlue skin and completing the category collation work.)


 * Education completed or in progress
 * August Witkowski Fifth High School in Kraków (2010–2013); finalist of the Polish Olympiad in Informatics (2013)
 * Computer Science undergraduate degree at AGH University of Science and Technology (2013–)


 * Will you have any other time commitments, such as school work, another job, planned vacation, etc., during the duration of the program?: Summer examination session at my university: 25 June – 8 July. None otherwise.

Past experience

 * Please describe your experience with any other FOSS projects as a user and as a contributor: I am, admittedly, not a FOSS advocate; I just use whatever is the best tool for a job, and that happens to include a lot FOSS projects like git, LibreOffice, Inkscape or MediaWiki. MediaWiki is by far the largest project I've contributed to. I've submitted bug reports and patches for various pieces of software (several Ruby gems, browsers like Firefox or Chrome, SublimeText plugins, other projects like meld) and written a few from scratch myself (all are available on my GitHub, unfortunately none has achieved wide-spread attention).


 * Please describe any relevant projects that you have worked on previously and what knowledge you gained from working on them (include links)
 * The most relevant major MediaWiki thing I did is most likely the CologneBlue skin rewrite (released with MediaWiki 1.21), during which I figured out how skins work internally and the interfaces they provide for skin creators. I also touched ResourceLoader in the past, learning a bit about its internals, mostly when working on  and   classes. The CologneBlue rewrite and some large cleanup projects like merging the common code of   and taught me how to manage large stacks of unmerged, dependent changes. All this makes me confident I have the chops needed to complete this project.
 * Apart from that my work so far focused on improving internationalization capabilities and JavaScript frontend code of MediaWiki, which are not really relevant here.