Jump to content

Separating skins from core MediaWiki

From mediawiki.org
Public URL
https://www.mediawiki.org/wiki/Separating_skins_from_core_MediaWiki
Bugzilla report
  • (task T62453) Core skins should initialise and include like other skins/extensions do
  • (task T45658) 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

[edit]
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

[edit]

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

Deliverables

[edit]

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 Skin and SkinTemplate classes.

Stage 1: Improve skinning mechanisms (task T45658)

[edit]

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. Yes 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. Yes 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. Yes Done, see Skin:Example, code available in the mediawiki/skins/Example repository.
    • (optional) Create a tutorial on this. Incomplete 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. N Not done
  • (optional) Convert at least one existing skin to new standard. Yes Done Modern, Cologne Blue, Nostalgia.

Make it easier to install and manage skins.

  • Consider deprecating current autodiscovery mechanism, with skins/Skinname.php file and 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. Yes 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. Yes 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. Yes 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. Yes Done, 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. N Not done, 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 (task T70333)

[edit]

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… Yes Done.
  • Audit all of core's CSS and JavaScript, remove anything skin-dependent. Incomplete Partially done, 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 (SkinTemplate allows one to build it easily) with none or minimal styles, and a big message suggesting installing some skins.

Incomplete Partially done:

  • Yes 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.
  • Yes Done Fallback skin has been implemented, patch: Use a special fallback skin when selected skin is unavailable.
  • Yes 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.
  • N Not done Tarball packaging process has not been updated during this project. The work is being tracked at bug 69248 and I will continue working with MediaWiki release managers on it.

Timeline

[edit]

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.

Progress

[edit]


Community bonding period

[edit]

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.

2014-05-20

[edit]

2014-05-22

[edit]
  • Reviewed changes to core and VectorBeta extension that aim to solve an incompatibility for custom skins using LESS stylesheets [4] [5]

2014-05-24

[edit]

2014-05-25

[edit]
  • 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.

2014-05-26

[edit]

2014-05-27

[edit]
  • 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.

2014-05-28

[edit]
  • 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).

2014-05-29

[edit]
  • 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.

2014-05-31

[edit]

2014-06-01

[edit]

2014-06-02

[edit]

2014-06-03

[edit]

2014-06-04

[edit]

2014-06-09

[edit]

2014-06-10

[edit]
  • 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

2014-06-11

[edit]

2014-06-15

[edit]
  • Skin autodiscovery is deprecated in master again (bug 66429).

2014-06-20

[edit]

2014-06-21

[edit]

2014-06-23

[edit]

2014-06-26

[edit]

2014-06-29

[edit]

2014-07-01

[edit]

2014-07-02

[edit]

2014-07-03

[edit]
  • 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.

2014-07-07

[edit]
  • Responded to code review.
  • Updated Manual:Skinning Part 1 's information about ResourceLoader modules.
  • Updated project page with thus newly (finally!) completed documentation items.

2014-07-09

[edit]

2014-07-12

[edit]

2014-07-15

[edit]
  • Responded to code review.
  • Reviewed and submitted some changes cleaning up references to Vector in mediawiki.ui [13] [14].

2014-07-18

[edit]
  • Completed the example skin [15].
  • Updated the skinning guide in some places that didn't work well in practice.

2014-07-20

[edit]

2014-07-21

[edit]

2014-07-22

[edit]

2014-07-23

[edit]
  • Submitted a ton of fixes for tests which would fail when the default skin was changed [16].
  • Submitted a minor tweak to Minerva skin. [17]

2014-07-26

[edit]

2014-07-27

[edit]

2014-07-28

[edit]

2014-07-30

[edit]

2014-08-04

[edit]

2014-08-06

[edit]

2014-08-07

[edit]

2014-08-08

[edit]
  • Responded to more comments on Wikitech, updated more documentation.

2014-08-09

[edit]

2014-08-13

[edit]

Participation

[edit]

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

[edit]

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.

Past experience

[edit]
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 CSSJanus and CSSMin classes. The CologneBlue rewrite and some large cleanup projects like merging the common code of SpecialWatchlist and SpecialRecentChanges 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.

See also

[edit]
Google Summer of Code:
Retrieved from "https://www.mediawiki.org/w/index.php?title=Separating_skins_from_core_MediaWiki&oldid=5328354"