 | This is anessay. It contains the advice or opinions of one or more Wikipedia contributors. This page is not an encyclopedia article or aWikipedia policy, as it has not beenreviewed by the community. |
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 determinewhen 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 iswrong, visible changes usually result inteacup storms no matterhow trivial the change.
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 evenmore 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 shouldalways be proposed in a suitably visible place beforehand. For well-watched interface messages such asMediaWiki:Sidebar or the .css/.js skin files, the corresponding MediaWiki talk: page is acceptable. For quieter messages, use theVillage 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 themerits 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 thetechnical details of your proposed change and ensure that it isn't going tobreak 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 thatwill 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 onMediaWiki:Watchlist-details?) Proposing changes before you make them is a simple way to avoidblanking the Main Page,wiping .js files orblacklisting multi-word titles.
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 attest.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 falsepositives as well as false negatives. For changes that absolutelyhave to be made to theactual message, get yourself admin status on another wiki (tryhttp://www.anarchytestwiki.org or ask for it aten.labs) and try the change there. Otherwise youwill 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 youhave broken something spectacularly, you can revert it yourself and avoidsome embarrassment.
The MediaWiki namespace operates under aone-revert rule. If your change is reverted, assume there is a good reason for it, anddon't add it back. Since only administrators are capable of editing the MediaWiki interface, edit-warring there is essentiallywheel warring, withvery serious potential consequences. If you made a change boldly without proposing it first, now is the time to do so. Thebold → 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 onhow 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 outwhich 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 problemworse. Useclue, rather thanrollback.
In general, it is not constructive to revert changes to the interfacejust 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 changewas discussed before being made, then contribute to that discussion instead of reverting; a revert would be its ownbold action. Of course, don't hesitate to take action to fix a broken change, no matterhow recent. Above all, usecommon sense – you're only in theposition to edit the interface because the community thought you had it.
| “ | Consider the mental welfare of the person who has to maintain the code after you | ” |
| — Larry Wall | ||
The MediaWiki interface is esoteric and complicated enough without adding to it with incomprehensible edits. Be particularly careful to documentwhat you're doing,why you're doing it andwhere it's being used, whenever any of these are not obvious. If you add styles inMediaWiki:Common.css, add a note tothe catalogue to say what the class does and where it comes from. If you do somethingcounterintuitive, it'sparticularly 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. Comparegenerally good withgenerally 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?