Separating skins from core MediaWiki
- Public URL
- Bugzilla report
- 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
- Bartosz Dziewoński
- IRC or IM networks/handle(s)
- freenode IRC: MatmaRex
- XMPP: firstname.lastname@example.org
- Web Page / Blog / Microblog / Portfolio
- Typical working hours
- afternoons and evenings CEST
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.
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
Stage 1: Improve skinning mechanisms (task T45658)
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
skins/ 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
LocalSettings.php (similar to what extensions do already).
- Document the expected directory layout. Done, documented at Manual:Skinning Part 1#Skin structure.
- Document how to define ResourceLoader modules and use them in the skin, making them work both in production and debug mode. Done, documented at Manual:Skinning Part 1#Skin styles and scripts (ResourceLoader modules).
- 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. Done, see Skin:Example, code available in the mediawiki/skins/Example repository.
- (optional) Create a tutorial on this. Partially done, the expanded Manual:Skinning Part 1 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. Not done
- (optional) Convert at least one existing skin to new standard. Done Modern, Cologne Blue, Nostalgia.
- (optional) Document the process of such conversion. I believe it will be straightforward enough that some examples will suffice. Done, documented at Manual:Skin autodiscovery#Migration guide.
Make it easier to install and manage skins.
- Consider deprecating current autodiscovery mechanism, with
skins/skinname/directory, in favor of the new system. It makes it unpleasant to add or remove skins, makes it hard to add skins to .gitignore. Done: 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. Done, 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 task T68440.
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. Done, patch: Allow skins to provide additional styles for any module.
- Consider deprecating
skinStyles, which allows the inverse: for modules to define styles only applied to certain skins. MediaWiki uses this heavily for core skins. Done, considered and not deprecated after all: both approaches have their use cases.
- Consider deprecating
- (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. the "Redo skin framework" RFC and it's better to let that happen.
Not done, this is one of the facets of
- 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 (task T70333)
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… Done.
- 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 (
SkinTemplate allows one to build it easily) with none or minimal styles, and a big message suggesting installing some skins.
- Done Modern and Cologne Blue, and then Vector and MonoBook, have all been moved to separate repositories and core MediaWiki no longer depends on them.
- Done Fallback skin has been implemented, patch: Use a special fallback skin when selected skin is unavailable.
- Done 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.
- bug 69248 and I will continue working with MediaWiki release managers on it. Not done Tarball packaging process has not been updated during this project. The work is being tracked at
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.
Community bonding period
I was already an active community member, so I focused on getting a hang on the skinning landscape (existing skins and their creators).
My goals for the first half of the internship are still the same as in the original proposal: defining the recommended way of structuring skins, improving their installation process and allowing third-party skins the same degree of freedoms core skins have.
As outlined in my proposal, I am using the wikitech-l mailing list for important discussions and major milestones, and IRC for day-to-day communication.
- Asked "What should be the recommended / supported way to do skins? (A proposal.)" on wikitech-l: http://lists.wikimedia.org/pipermail/wikitech-l/2014-May/076591.html
- Commented on pending changes aiming to move some skins out of core   
- Reviewed changes to core and VectorBeta extension that aim to solve an incompatibility for custom skins using LESS stylesheets  
- Replied to the discussion with a summary and some action items. http://lists.wikimedia.org/pipermail/wikitech-l/2014-May/076671.html (life interfered with my plans to do this earlier)
- Cleaned up the category tree of Category:Skinning a bit, fixing skin documentation pages and renaming several categories
- Started the work on deprecating skin autodiscovery, tracked on bug 65748.
- Complete list of patches about skin autodiscovery, finished today:
- https://gerrit.wikimedia.org/r/#/c/135383/ (master) "Don't use autodiscovery for core skins"
https://gerrit.wikimedia.org/r/#/c/135384/ (master) "Move core skins to separate directories"See https://gerrit.wikimedia.org/r/#/c/135383/
- https://gerrit.wikimedia.org/r/#/c/135429/ (master) "Officially deprecate skin autodiscovery"
- https://gerrit.wikimedia.org/r/#/c/135427/ (REL1_23) "Officially deprecate skin autodiscovery"
- https://gerrit.wikimedia.org/r/#/c/135439/ (master, on hold) "Completely remove skin autodiscovery"
- https://gerrit.wikimedia.org/r/#/c/118345/ "Move Modern and CologneBlue out of core" and related patches were merged by Chad. I was planning to do this in the second half of the project, but it might as well be done now.
- Fixed some minor issues with the merged patches related to the above, got poked myself and poked Chad about getting it deployed on Wikimedia wikis (tracked on bug 65868).
- Modern and CologneBlue moved out of core and deployed on testwiki: everything seems to work. As I was not planning to spend time on this right now, it might delay my schedule a little, but in the worst case I'll be able to regain the lost time in the second half of the project (which has just been partially done thanks to Chad's help).
- "Officially deprecate skin autodiscovery" merged into REL1_23.
- Worked on deprecating old functionality: reviewed, updated and merged https://gerrit.wikimedia.org/r/#/c/63364/, submitted https://gerrit.wikimedia.org/r/#/c/136531/ and related patches to existing skins (Modern, CologneBlue, Nostalgia).
- Cleaned up and updated Manual:Skinning Part 1 in preparation for expanding it.
- Wrote initial version of Manual:Skin autodiscovery and added release notes at MediaWiki 1.23#Skin autodiscovery deprecated.
- Gotten https://gerrit.wikimedia.org/r/#/c/135408/ merged, which blocked separating MonoBook from core.
- Further Manual:Skin autodiscovery work.
- Submitted patches for converting Nostalgia into a proper skin. https://bugzilla.wikimedia.org/show_bug.cgi?id=61256#c5
- Updated the status of deliverables on the project page.
- Manual:Skin autodiscovery should be complete and usable now.
- Skin autodiscovery deprecation patches were merged, and then one was reverted again because of WMF CI issues (bug 66429).
- Added support for enabling skins in MediaWiki installer, pending review: https://gerrit.wikimedia.org/r/138652
- Wrote tentative patches to separate Vector and MonoBook skins from core: https://gerrit.wikimedia.org/r/#/c/135413/ https://gerrit.wikimedia.org/r/#/c/138795/. Hopefully these can be finalized soon and the skin directory layout can be documented.
- Skin autodiscovery is deprecated in master again (bug 66429).
- Rebased several patches that became outdated.
- Took part in a meeting where I responded to questions about what I'm doing and discussed about the replacement for
skinStyles: Architecture meetings/RFC review 2014-06-20.
- Nostalgia skin patches from bug 61256 have been merged.
- The patch to separate Vector from core (https://gerrit.wikimedia.org/r/#/c/135413/) has been merged, the one for MonoBook is on the way.
- MonoBook patch (https://gerrit.wikimedia.org/r/#/c/138795/) has been merged as well.
- Submitted several patches to improve information shown on Special:Version for all the skins that have been split from core recently (   ).
- Submitted a patch to allow skins to define
skinStylesfor arbitrary modules after discussing the approach with ResourceLoader developers. https://gerrit.wikimedia.org/r/#/c/141259/
- Worked with Nikerabbit and Reedy to fix an issue with translations for the Vector skin not being loaded. After the skin with its localisation messages was split, the translations did not follow due to a combination of bugs and mistakes. https://gerrit.wikimedia.org/r/#/c/141303/ https://gerrit.wikimedia.org/r/#/c/142270/ https://gerrit.wikimedia.org/r/#/c/142271/ https://gerrit.wikimedia.org/r/#/c/142273/
- Follow-up for Vector splitting to fix i18n conflict with Vector extension: https://gerrit.wikimedia.org/r/#/c/142277/
- Patch to separate skins and extensions on Special:Version merged. https://gerrit.wikimedia.org/r/136615
- Follow-up to the Vector i18n follow-up: https://gerrit.wikimedia.org/r/#/c/142968/
- FIxing an issue with the temporary skin requires in Setup.php. https://gerrit.wikimedia.org/r/143302
- Completed and tested the installer patch https://gerrit.wikimedia.org/r/#/c/138652/, discovering and fixing two pre-existing bugs https://gerrit.wikimedia.org/r/#/c/143702/ https://gerrit.wikimedia.org/r/#/c/143703/.
- Updated information about skin structure on Manual:Skinning Part 1, hopefully for the last time.
- Updated the same page about new localisation messages format introduced in MediaWiki 1.23.
- Responded to code review.
- Updated Manual:Skinning Part 1's information about ResourceLoader modules.
- Updated project page with thus newly (finally!) completed documentation items.
- Finished Nostalgia cleanup (bug 61256).
- Responded to code review.
- Finished updating Manual:Skinning Part 1.
- Summarized the earlier skin standard discussion: http://lists.wikimedia.org/pipermail/wikitech-l/2014-July/077567.html
- Submitted a patch to change MediaWiki to accept skin identifiers in any letter case https://gerrit.wikimedia.org/r/#/c/145874/.
- Responded to code review.
- Reviewed and submitted some changes cleaning up references to Vector in mediawiki.ui  .
- Completed the example skin .
- Updated the skinning guide in some places that didn't work well in practice.
- More tweaks to the example skin.
- Submitted https://gerrit.wikimedia.org/r/147901 to fix a tiny regression I caused when separating Vector skin from core earlier.
- "Support for enabling skins in the installer" https://gerrit.wikimedia.org/r/138652 merged.
- Did some updates on Bugzilla.
- Finished, published and publicized the example skin (https://gerrit.wikimedia.org/r/#/c/147690/). See Skin:Example and http://lists.wikimedia.org/pipermail/wikitech-l/2014-July/077727.html.
- Submitted https://gerrit.wikimedia.org/r/148139 "mediawiki.page.watch.ajax: Remove #bodyContent, #content restriction on the link", the current way is incompatible with third-party skins.
- Submitted more changes dependent on the (pending) skinStyles replacement https://gerrit.wikimedia.org/r/148304 https://gerrit.wikimedia.org/r/148305.
- Implemented the fallback skin with help messages https://gerrit.wikimedia.org/r/148508 and a method of using it https://gerrit.wikimedia.org/r/148424.
- Submitted several other minor patches.
- Updated the bug tree of bug 68333, filing some sub-bugs to work on in near future.
- Started preparations towards splitting off Vector and MonoBook from core. The patch https://gerrit.wikimedia.org/r/148509 currently still causes test failures.
- Submitted a ton of fixes for tests which would fail when the default skin was changed .
- Submitted a minor tweak to Minerva skin. 
- Merged https://gerrit.wikimedia.org/r/148846 instead of my own https://gerrit.wikimedia.org/r/#/c/148766 to fix one of the test issues.
- Responded to code review.
- Submitted https://gerrit.wikimedia.org/r/149779 to fix one more issue with not having any usable skins.
- Submitted https://gerrit.wikimedia.org/r/149780 for MobileFrontend to move some of Minerva skin's styling from core hacks to there.
- Rebased dependencies for splitting off Vector and MonoBook (https://gerrit.wikimedia.org/r/#/c/148509/2).
- Abandoned https://gerrit.wikimedia.org/r/148766 in favor of a different approach.
- $wgResourceModuleSkinStyles patch and some friends were merged.
- Emailed wikitech-l about upcoming changes in the skin system: http://lists.wikimedia.org/pipermail/wikitech-l/2014-July/077835.html
- Created Manual:$wgResourceModuleSkinStyles and emailed wikitech-l about the new functionality being available: http://lists.wikimedia.org/pipermail/wikitech-l/2014-July/077878.html.
- Submitted a patch to fully migrate Minerva skin to $wgResourceModuleSkinStyles: https://gerrit.wikimedia.org/r/#/c/150580/
- Finalized the fallback skin changeset after input from reviewers: https://gerrit.wikimedia.org/r/148508
- Replied to concerns about skin system changes: http://lists.wikimedia.org/pipermail/wikitech-l/2014-August/077960.html
- Contacted a few people at Wikimania about finalizing the skin changes, in particular in the context of Wikimedia deployment.
- Worked with other developers at Wikimania Hackathon to merge all of the changes necessary to move MonoBook and Vector to separate repositories: https://gerrit.wikimedia.org/r/152265 https://gerrit.wikimedia.org/r/152267 https://gerrit.wikimedia.org/r/148433 https://gerrit.wikimedia.org/r/152266 https://gerrit.wikimedia.org/r/148509
- Emailed wikitech-l about the change again, responded to comments and updated documentation.
- Worked to fix breakages in Beta Labs and Vagrant related to this change.
- Submitted a follow-up to $wgResourceModuleSkinStyles support: https://gerrit.wikimedia.org/r/#/c/152244/
- Responded to more comments on Wikitech, updated more documentation.
- Submitted a follow-up to Special:Version changes: https://gerrit.wikimedia.org/r/#/c/152991/
- Updated Manual:Skin configuration.
- Updated all kinds of stuff, really.
- Submitted a little patch for Wikimedia configuration to correctly show skins' versions on Special:Version: https://gerrit.wikimedia.org/r/#/c/153127/
- Updated release notes and README: https://gerrit.wikimedia.org/r/153881
- Documented the user-facing changes at MediaWiki 1.24#Skins no longer loaded after upgrade?.
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).
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
- 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.
- 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
CSSMinclasses. The CologneBlue rewrite and some large cleanup projects like merging the common code of
SpecialRecentChangestaught me how to manage large stacks of unmerged, dependent changes. All this makes me confident I have the chops needed to complete this project.
- User:Jack Phoenix/A modern, scalable and attractive skin for MediaWiki (GSoC 2014 proposal) – another skinning-related GSoC proposal. It is only tangenially related to mine and the two should not conflict in any way; if anything, completing one of them could make the other more beneficial to MediaWiki and vice versa.