Global templates/Transition

The implementation of Global templates and modules has two sides:


 * 1) The creation of the repository and the infrastructure that makes it possible
 * 2) The work by editors of multiple wiki projects to move the existing templates to this repository.

The “” document primarily addresses the infrastructure. (Also, as of June 2020, it mostly speaks about it on the level of product requirements and not on the level of internal technical architecture.)

This document here tries to address the other side: How will editors of wiki projects use this infrastructure once it’s available. It may seem that writing such a document so early in the process is too far-fetched because doing any of these things will be possible only when the infrastructure is actually deployed. However, it is useful to try to think about it as early as possible because it can inform the development of the technical infrastructure and the planning of its implementation. It may also help the developers understand which parts of this process can be at least partly automated. Once the infrastructure exists, this page will be converted from a theoretical plan to a practical transition guide.

As with all the other documents about Global templates, this is not the work of one person or a small group. The comments of all editors, developers, and other stakeholders are welcome—otherwise it just won’t work.

What happens today
So, let’s say that you want to write an article in the Wikipedia in your language about the city of Shanghai, and you want to have in it an infobox like the one in the English Wikipedia article about it. You figure out that you have to type, but when you publish, you see a red link: Template:Infobox settlement. So you figure out that you probably have to copy the whole template to your wiki.

If you don’t know much about programming and wikitext (also known as wiki syntax), then you have these options:


 * 1) Make a simpler template with fewer features.
 * 2) Make a table that looks kind of like the infobox. (And then make such a table in every article about every city.)
 * 3) Just give up and have an article about Shanghai without an infobox.

If you do have some time and some knowledge about programming and wikitext, then here’s a simplified list of what you’ll have to do:


 * 1) Copy the code of this template to your wiki. As of this writing, it’s 57,071 bytes and 940 lines.
 * 2) Realize that this template actually uses a lot of other templates. Learn how to use Export feature. Export the template, with the  option enabled. As of this writing, this will import 130 templates and modules, and the XML dump will have more than 40,000 lines.
 * 3) Go through all the wiki syntax code you copied, find all the human-readable user interface strings that have to be translated, and translate them. Be careful not to touch parameters and parser functions.
 * 4) Go through all the wiki syntax and Lua code that you copied in 130 templates and modules, find all the parameter names and where they are used, and change them to your language. (This step is optional, but useful for editors who don’t know English.)
 * 5) Change the parameter names in TemplateData, but keep the English names as aliases.
 * 6) Copy the documentation pages, delete all the English text from them, and write the same text in your language. Be careful to change the parameter names.
 * 7) Check that the template actually works and does what you need. If it does not, you may have to search for CSS or JS pages on which it depends.

(This doesn’t apply to the current version of, but on many other templates you’ll also have to copy the TemplateStyles. This will be done automatically by the export tool, but you’ll have to verify that it actually worked.)

You have to do all of this for every template that doesn’t exist in your wiki. And it has to be done in every wiki. That’s basically the problem that the Global templates proposal is trying to solve.

Working together
A cross-wiki community of template and module maintainers will have to arise as early as possible. It must be truly global, serving all projects equally: Wikipedia, Wikidata, Commons, and even the less famous projects, such as Wikinews and Wikispecies. All wikis need global templates and there must be no preferential treatment.

TODO: Add some more details about cross-wiki community building...

What to migrate
It was discussed several times what templates and modules should be migrated, for example on the pages meta:Which templates should be global? and Multilingual Templates and Modules. All the proposals there make sense.

One approach may be to define which are the most used modules and templates across versions and projects, and then start the migration from there. Attention: the keyword here is used, not needed, since this will help us on two different levels:
 * 1) Focusing on what is already a core functionality across projects; and
 * 2) Demonstrating that the whole project works and has positive feedback for involved communities.

Potential candidates for this “phase 1 migration” might be:


 * Module:Arguments, used on ~340 projects
 * Module:String, used on ~285 projects
 * Module:No globals, used on ~275 projects
 * Module:Wikidata, used on ~140 projects
 * Template:Ambox, used on ~350 projects
 * Template:Speedy delete, used on 820 projects
 * Template:Bot, used on 654 projects
 * All the modules managed by the bot, because they are already global in practice.
 * The various Cite templates and modules

And so on. A more precise list of potential candidates can be this one. (It should be noted how many “universally needed” modules and templates are not present in all projects, one more time underlining the necessity of such a project)

What should be avoided, though, it’s a potential feeling of imposing something to the community. This can arise when locally a module or a template has been modified to the point that it’s not similar to the one of other communities. For this reason, phase 1 should probably limit to “non-controversial modules and templates”, i.e. modules and templates with the most basic functionalities as possible—speedy deletions, boxes, and such.

Migrating
''TODO: This is only an outline. The section will be rewritten in more detail''

Many of the actions are the same for templates and the modules, so they are given together. It's split where relevant.

Migrating the first version of a template or a module from a local wiki to the global repo
Every template or module can be a candidate for moving to the global repository. If, for any reason, a template or a module is supposed to remain local, it should be tagged accordingly.


 * Check that it is not already available in the global repo. If it is already there, proceed to the next section.


 * Recursive: If this module or template uses other modules or templates, migrate them first.
 * Export the template or the module page and its documentation page from the local wiki and import it to the global repo. Add sitelinks to the imported pages in the corresponding Wikidata item pages.

Making it translatable
If this template or module is intended for use in several wikis in the same language, then translatability is not required and this whole section is optional.


 * Find all the human-readable strings that are displayed to users:
 * Modules: Find all the instances of literal strings in quotation marks in Lua code. Skip those that are used internally, and process only those that are actually displayed to users.
 * Templates: Find all the strings that are not pure wiki syntax (tables, links, other tempalte invocations,, etc.). Note that template parameters are treated separately!
 * Move all the strings to a separate storage and replace them with message keys.
 * Modules: Remove the literal strings in quotation marks in Lua code and change them to in message keys. (How will this actually work is to be determined, see .)
 * Templates: Remove the literal strings from the template and replace them with message keys in the wikitext. (How will this actually work is to be determined, see .)
 * TBD: Another option is to do something like what is done in the TNT system: add tags and translate them like a translatable page.
 * Make the strings translatable using Translate:
 * Make sure that this template or module is conveniently discoverable in the project selector.
 * Add message documentation (known as "qqq" in core and extensions) so that translators would understand the context.
 * Apply the usual best practices from the page.
 * Make the template or the module usage documentation translatable as a translatable page. (TODO Consider creating association between the UI strings translation and the documentation translation.)
 * For templates: Make the template’s title and parameter names translatable. (How will this actually work is to be determined, see .)

Discarding the local wiki page when creating the first version in the global repo

 * Delete the template or the module and its documentation from the local wiki.
 * Test that the template or the module still works as expected in the local wiki. Fix it if it can be fixed quickly, or restore the local template or module if it's not trivial.

Switching from a local template or module to a version already available in the global repo
This should be done in every wiki in which a version of a template or a module that is already available in the global repo exists.

Start from comparing the code of the template or the module to the code in the global repo.

If the code is the same as the one in the global repo

 * Translate the template or the module’s strings into the wiki’s language. (This is optional, but highly desirable.)
 * Go to the "Discarding" section.

If the code is different
Was the template or the module imported some time ago, left unchanged, but updated in the other wiki? If the updates there are useful for your wiki, and the parameters are compatible with the current usage in the local wiki, do the same as in the "If the code is the same" section.

Was the template or the module imported some time ago, and changed only to adapt it to the local language? Copy the translated strings from the local wiki to the localizable module in the central repo. If there are no other differences, do the same as in the "If the code is the same" section.

Was the template or the module imported some time ago, and had some non-trivial functional changes? Or is it a module that has similar functionality, but was developed separately? Decide in the local wiki on a case by case basis. The main imaginable decisions are (in no particular order):


 * Stop here and keep the local module. Tag it as "don't move to the global repository", and explain why.


 * Decide that the local changes are not that important, and do the same as in the "If the code is the same" section.
 * Copy the local changes to the global module, making them usable for all wikis. This must be done only after making sure that they don’t break the module for other wikis and don’t make the global module harder to maintain.
 * Split the local module: Move the local changes to another module, and discard the local module.

Discarding the local wiki page in favor of a version in the global repo

 * Templates: If needed, localize the template title and parameters. (How will this actually work is to be determined, see .)
 * Check the parameters:
 * Modules: Check that the local and the global module have the same parameters. If they are not compatible, replace the current invocations of the module to use parameters that are compatible with the global module. This can often be done with a bot, but sometimes may have to be done manually.
 * Templates: Check that the local and the global template have the same parameters. They may be localized for your language, but the names must be mapped in the global repository. (How will this actually work is to be determined, see .) If they are not compatibe, replace the current transclusions of the template to use parameters that are compatible with the global template. This can often be done with a bot, but sometimes may have to be done manually.
 * Test that the global template or module works as expected in the local wiki. Fix if needed.
 * Delete the local wiki page with the tempalte or the module.

Concluding

 * If you found anything problematic during the migration process, update this guide and document it.

Migrating templates
TO BE MERGED WITH THE MIGRATING SECTION

''TODO: This is only an outline. The section will be rewritten in more detail''

This process is similar to the process for modules, but there are also some differences.


 * Recursive: If this template uses other templates or modules, migrate them first.
 * Copy the template and its usage documentation page from the local wiki to the global repo. Add a sitelink to it in the template’s Wikidata item.
 * Find which CSS styles does the template use. Some of them will be in TemplateStyles, and some of them will be in Common.css or other wiki pages. Copy them to the global repository.
 * Make the template translatable:
 * Find all the human-readable strings.
 * Move all the strings to a separate storage and replace them with message keys in the wikitext (how will this actually work is to be determined, see .)
 * TBD: Another option is to do something like what is done in the TNT system and add tags.
 * Make the strings translatable using Translate:
 * Make sure that it’s conveniently discoverable in the project selector.
 * Add message documentation (known as "qqq" in core and extensions) so that translators would understand the context.
 * Apply the usual best practices from the page.
 * Make the template usage documentation translatable.
 * Make the template’s title and parameter names translatable.
 * Delete the template and its documentation from the local wiki
 * Delete the template’s CSS styles from the local wiki, unless:
 * These styles are also used by other templates that were not yet migrated to the global repo.
 * These styles need to remain customized in the local wiki, and the customizations cannot be moved to the global repo conveniently.
 * Go over each wiki in which the template exists:
 * If the wikitext is the same as the one in the global repo, delete it from the local wiki
 * If the wikitext is different:
 * Was the template imported some time ago, left unchanged, and updated in the other wiki? If the updates there are good and the parameters are compatible with the current usage in the local wiki, delete it from the local wiki and switch to using the global template.
 * Was the template imported some time ago, and changed only to adapt it to the local language? Copy the translated strings from the local wiki to the localizable template in the central repo. If there are no other differences, delete it from the local wiki and switch to using the global template.
 * Was the template imported some time ago, and had some non-trivial functional changes? Or is it a template that has similar functionality, but was developed separately? Decide in the local wiki on a case by case basis. The main imaginable decisions are (in no particular order):
 * Stop here and keep the local template.
 * Decide that the local changes are not that important, and delete the local template and switch to the global template.
 * Copy the local changes to the global template, making them usable for all wikis. This must be done only after making sure that they don’t break the template for other wikis and don’t make the global template harder to maintain.
 * Split the local template: Move the local changes to another template, and delete the local template.
 * If you are deleting the module from the local wiki in favor of a global module:
 * Check that the local and the global module have the same parameters. If not, replace the current invocations of the module to use parameters that are compatible with the global module. This can often be done with a bot, but sometimes may have to be done manually.
 * Delete the template’s documentation.
 * Delete the template’s CSS styles from TemplateStyles or CSS wiki pages, unless these styles need to remain customized in the local wiki, and the customizations cannot be moved to the global repo conveniently.
 * Test that the template still works as expected in the local wiki. Fix if needed.
 * If you found anything problematic during the migration process, update this guide and document it.

Cross-wiki diff
A tool that shows a diff between revisions of wiki pages on two separate wikis. This would be useful for checking whether the module or the template is the same as on another wiki or the global repo.

Dependency look up
A tool that gets a list of the templates and the modules that a given template or module uses, and checks which ones are already global

Module string migrator
A tool that finds all the strings in Lua code and helps migrate the human-readable ones to message storage and replace the strings in the code with message keys.

Template string migrator
A tool that finds all the strings in wikitext and helps separate them from wikitext by migrating them to message storage and replace the strings in the code with message keys or by adding tags.

When the dust settles
''TODO: This is only an outline. The section will be rewritten in more detail''


 * Some issues to address:
 * Where are the new modules and templates created?
 * How are changes coordinated between different wikis?

Looking even further into the future
''TODO: This is only an outline. The section will be rewritten in more detail''


 * Making templates semantic: making them accessible from VE toolbar, more machine readable, etc.
 * Wikilambda