Wikipedia:Editing the interface

This is intended to be a 'best practice' guide for administrators editing the MediaWiki interface. Whilst not necessarily an enforceable policy or guideline, it is intended to provide useful suggestions.

Editing the MediaWiki interface causes changes that can potentially affect millions of users. Since parts of the interface (particularly .css and .js files) are cached in users' browsers, any mistakes made are not only highly visible, but can persist for up to a month after they are resolved. In addition, changes can be hard to locate amongst the numerous MediaWiki system messages, and (when the messages edited appear infrequently) it may be difficult to even determine when a change was made.

In addition, changes that alter the appearance of the site interface regularly attract a storm of protest from users who preferred the 'old' appearance, whatever it might have been. As, naturally, both the old and new appearance is wrong, visible changes usually result in teacup storms no matter how trivial the change.

Propose visible changes

It is not the case that the 'be bold in editing pages' philosophy does not apply to the MediaWiki interface. With only administrators able to edit these pages, it is if anything even more important to boldly update and ensure that it is using the latest features and tools. However, there is a world of difference between an update that changes a well-established feature or setting and affects many or all users, and an update that silently improves the handling or cleanliness of existing features.

In general, it is not a good idea to make bold edits that visibly change or, most dangerous of all, remove existing features. Such changes should always be proposed in a suitably visible place beforehand. For well-watched interface messages such as MediaWiki:Sidebar or the .css/.js skin files, the corresponding MediaWiki talk: page is acceptable. For quieter messages, use the Village Pump. Be specific about what you want to change, especially if it involves complicated code (in any language).

The benefit of proposing changes before you make them is twofold. First of all, it enables other editors to give their comments on the merits of the proposed change, and thus takes some of the power out of the aforementioned teacup storm. Secondly, it allows editors with a wide range of technical knowledge about the MediaWiki software to analyse the technical details of your proposed change and ensure that it isn't going to break anything. The MediaWiki: namespace contains pages written in seven languages (CSS, JavaScript, wikimarkup, RES, HTML, regex and plaintext); mixing syntax or forgetting the rules of the page you're editing is not just a possibility, it's something that will happen. Even if you manage to avoid the obvious pitfalls, there are innumerable little details that will catch you out (did you know, for instance, that you need to put an   at the end of each entry on MediaWiki:Watchlist-details?) Proposing changes before you make them is a simple way to avoid blanking the Main Page, wiping .js files or blacklisting multi-word titles.

Test everything

It doesn't matter what you're changing or how infintesimally small the change is, test it first. For .css and .js files, work out everything in your own custom files first. Get an account at test.wiki to prevent conflicts between the 'live' code and your test code; you can copy the contents of the .css or .js file you're playing around with over there and edit it at will. For regular expressions, whack it into a regex tester first, no matter how simple it is. Test against false positives as well as false negatives. For changes that absolutely have to be made to the actual message, get yourself admin status on another wiki (try http://www.anarchytestwiki.org or ask for it at en.labs) and try the change there. Otherwise you will be caught out when you try adding wikimarkup to a message that only accepts HTML, or vice versa.

Once you've tested it thoroughly and implemented it (with or without prior proposal), test it again. That way if you have broken something spectacularly, you can revert it yourself and avoid some embarrassment.

Revert and discuss

The MediaWiki namespace operates under a one-revert rule. If your change is reverted, assume there is a good reason for it, and don't add it back. Since only administrators are capable of editing the MediaWiki interface, edit-warring there is essentially wheel warring, with very serious potential consequences. If you made a change boldly without proposing it first, now is the time to do so. The bold → revert → discuss cycle operates particularly well in the MediaWiki: namespace; if someone reverts your changes, it is indicative that they didn't have the effect you intended, or that the intended effects were not universally considered positive.

If you are an administrator and encounter a bold change to the interface, your actions should depend on how you found it. If it's because you're tracking down an error or responding to complaints, then you should feel free to undo the change. Unless the issue is urgent, however, take a little time to work out which changes to undo; very often, administrators will make several sequential changes to a system message, and usually only one of these is the cause of the problem. Blithely reverting all recent edits risks discarding positive contributions, and can in some cases actually make the problem worse. Use clue, rather than rollback.

In general, it is not constructive to revert changes to the interface just because they were implemented without discussion, and administrators should refrain from doing so. Revert only if you have a reason to, although that reason can be a personal preference – IDONTLIKEIT arguments are fine if there's been no discussion. If the change was discussed before being made, then contribute to that discussion instead of reverting; a revert would be its own bold action. Of course, don't hesitate to take action to fix a broken change, no matter how recent. Above all, use common sense – you're only in the position to edit the interface because the community thought you had it.

Document things

The MediaWiki interface is esoteric and complicated enough without adding to it with incomprehensible edits. Be particularly careful to document what you're doing, why you're doing it and where it's being used, whenever any of these are not obvious. If you add styles in MediaWiki:Common.css, add a note to the catalogue to say what the class does and where it comes from. If you do something counterintuitive, it's particularly important to be clear as to why. Edit summaries are especially important: if your work has to be undone in a hurry, the clearer you are, the easier it is. Compare generally good with generally bad. If the change has been proposed and discussed, indicate that discussion in the edit summary; otherwise how is anyone to know that it is anything more than a bold change?

• Wikipedia:Catalogue of CSS classes