Wikipedia:Changing templates

This page describes problems that are faced when changing templates that have a significant number of calls.

Two classes of changes:

Assume you have a heavy use template like template:cite book and you want to change something on that template (assuming there is consensus for that change).

Template changes can be categorized into two classes:

Changes that are compatible with existing calls (A)
Changes that are incompatible with existing calls (B)

Class A changes are no problem. You can simply change the template and you are done. If the change was bad, you can simply revert that and everything is fine.

Class B changes are problematic. These kind of changes require changing all calls to the template to be compatible with the new version of the template.

Examples for Class A changes:

Changing the text that the template emits
Deprecating a parameter (although this may lead to later surprises if it is readded by an unwary Wikipedian)

Examples for Class B changes:

Renaming a parameter
Changing the specification/requirements on how a parameter is to be used

Class B changes

The brute force method

The brute force method is to just boldily change the template, ignoring for a moment that the change breaks the calls and then rushing around on the wiki, quickly fixing the calls to get them in line with the new version of the template.

Drawbacks:

Each page P transcluding the changed template T are broken, until the calls on P to T are migrated to the new version of T.
Failures while doing the migration on page P watched by third party wikipedians W3 having P on their watchlist may lead to reverts on P. But such a revert doesn't fix the page either, because the page needs to be changed. This has a high frustration potential for third party watchers.
Such frustration and misunderstanding by observer Wikipedian W3 may lead to the point where W3 identifies the "offending" template T and goes to revert the class B change there.
This revert naturally happens right in the middle of the process with calls half-way migrated, with the effect that the already migrated calls are now broken (because the migrated call is incompatible with the old version of T) and the not yet migrated ones are again ok.
The brute force method is nothing more than a good faith attempt, because it takes a certain amount of time to migrate the calls. During this time, a page Q that needs to be migrated can get protected. If the Wikipedian that migrates the calls doesn't have the admin bits, the migration will remain incomplete until an admin fixes page Q, further increasing the risk that W3 reverts T. The migrater can show some care and create a list of pages upfront and check that all pages are unprotected. But during the process, the original precondition may change. Even worse, the list of pages that need to be migrated can change, because uninformed Wikipedians may insert new calls after the migration already has begun.

In short: especially for high use template this can result in a minor-wiki drama, especially if very prominent pages are affected (example of a sensitive template: template:Infobox President, which is transcluded in George W. Bush).

Migrating to a new template

The safest method to avoid the problems of the brute force method, is to create the new version of the template under a different name and migrate all calls to the new name. This has the following benefits:

Old calls that don't need to be migrated like calls from talk archives or talk pages anyway can still use the "old" template.
Pages that are protected can still use the old template and they don't look broken. They can be migrated anytime an admin has time or when the page is finally unprotected.
New calls that are inserted by Wikipedians during the migration can later be migrated. So migration can happen in bursts until the what links here of the old template is emptyfied enough.
Already migrated pages appear on the What links here of the new template, so pages that are already migrated can be easily found. It is also easy to create a list of the pages that have not yet been migrated (What links here of the old template).
Failed migration edits on articles can be easily reverted by page watchers if they see any problem. This reduces stress on all sides.

During the migration phase, both the old and the new template "version" are available for transclusion.

Drawbacks:

You need a new name for the new version of a template ("T2" or whatever). This spoils the notion of a "standard" template.
Looks like a fork for the uninformed. A deprecate notice should be placed on the old template. In later phases, this can even be a message that is transcluded into the calling pages, ultimately notifying that this template is out of service.