Module:Centralizer:CentralDescription.xml

This documentaion is only in draft state. Some parts are empty or missing

Central modules in brief

The Centralizer module is primarily an installer of 10 libraries. When they become available as part of Scribunto, it will no longer be needed. The normal evolutions will then be done for these libraries. In 2019, it is internationnal, using some minimal i18n translations tables. A sub-module named Centralizer:Module/I18N is made to contain available translations. Add, or adjust, a new langage need only to change this Centralizer:Module/I18N.
They are also multi languages as able to use in one run the content language, the page language and the user langage.
They are multi wikis using the future Phabricator task T121470 "Begin T121470 Central Global Repository for Templates, Lua modules, and Gadgets"
This task permit to use in local any central Lua module.
The Lua part of central modules support contains 10 libraries used by central modules.
The first test is dated of Xmas 2013.
On january 2019 they are based on 10 libraries installed by the Module:Centralizer which must be used in each wiki/language in the last version.
These continue until they become parts of Scribunto.

In this document, Library: is not a namespace, only a way to shortly express that an object is understood as a library.
Each new language need only to translate 300 short texts.
See convert a module as central.

The central system permits to convert any module as central.
Central libraries are intimately dependent of each other. Examples: the Library:versions installs others and the Library:viewers is usefull anywhere.

Why central modules

Current modules are made for one wiki and one language. They need Lua-coders to translate and adapt them for another wiki or language.
Errors in them are corrected in one wiki/language but continue in others.
Small wikis do not have Lua-coders to translate them and can not use them.
In this way, many small wikis have no or few modules. Existing ones are not easy to debug elsewhere. The effort to re-use them is very heavy.
Then central modules can solve many questions.

Documentations and cooperation

This manual documents the Lua part of central modules support for any central modules in w:Lua as they are used in MediaWiki with the Scribunto extension.
See also the Tactics Manual:Developing libraries.

• Guideline of central modules.
• MediaWiki:Scribunto/Central modules reference manual
• The main present Module:Central installs central libraries. It is in French Wikisource.
• Template example: Modèle:Central
• Main module example: Module:Author3
• Example of module for an author: fr:Utilisateur:Rical/Victor_Hugo
• Small wiki example of central tests: Vietnamese Module Documentation
• Translations support: Translating:MediaWiki, and its statistics.
• Scribunto extension
• Extension:Wikibase Client/Lua

The Phabricator task T20180527 "Begin to use central modules", invite you to cooperate about the transfert of know-how.
During this phase Lua-coders need to cooperate.
They could dialogate in Discussion MediaWiki:Scribunto/Central guideline.

Tests pages

Central libraries: Module:Central.
Simple examples of uses: Module:Central/Documentation
Full example: User:Rical/Victor_Hugo.

Stability

Central modules specially must be stable. Some supports for stability:

• Central modules must follow S.O.L.I.D recommendations. Lua-coders can ask help from their pairs if necessary, see https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)
• Which kind and level of stability do we need to begin to use central modules?
• Which kind and level of stability do we need to really centralize?
• How to insure a hight level of stability?
  • Run many tests for key functions.
  • Display groups of tests for Lua-coders. Then they can detect errors or missing tests cases.
  • Notify and alert central Lua-coders using errors and categories.
  • Document all functions supporting stability and listing all actual fonctions to not miss some ones.
  • Save and restore main configurations for each group of tests to better avoid mutual perturbations between them.
  • Display tests in any documentations pages, always up-to-date.
  • Search other means to increase the stability and report them.

Stability Tactic

Some questions are especially important for all developers in the early phase of the deployment of central modules.
Libraries and functions names must be stable before a large deployment to reduce the renaming of them.
That could imply heavy corrections after the begin phase.
Stability questions:

• How to name central libraries ?
• How to name functions in these libraries ?
• How to distribute the functions in one or some libraries ?

Some examples:

• The Library:lua_table enhances the table library from the Lua language, to avoid ambiguities.

To enhance Scribunto table, we could write: lua_table = table.

• Too diversity in the styles of variables names result in difficulties to remember their names for Lua-coders. They are sources of errors and of losts of time.
• How to distribute the functions in one or some libraries ?
• The categories "Module with internal error" and "Module with usage error" duplicate and group some other categories for an easier help from Lua-coders. Also they need different competences from helpers. How to enhance these supports?

Do we want a library args separed from the existing library modes, to easier identity the main job of each function?

Stability tasks

• The versions library installs sought sub-modules using versions support.
• Drop boxes and tables views help to easy format new tests.
• The activity library help to manage sub-tasks and phabricator tasks, between Lua-coders, projects and languages.
• The tracker object supports parametrable track objects to help to debug the Lua code.
• The events library formats events as errors, warnings and categories.
• In many functions in the Lua code, strict type checks of values reduce errors risks.
• The initial development in the same text file enhance the cohesion in values, variables and functions.
• The function viewers.save_restore_balance_report checks and reports known couples of save and restore global configurations to reduce interferences between tests.

Central supports

The central system permit some new supports.

Languages support

Central modules support translations in many languages, using i18n tables.
They support also the content, page and user languages.
The system can also suggest a default local language depending where the module is used.
For these goals, central modules get these languages from the system, modes, options, arguments and tests cases.

Translations support

The langs library supports i18n translations.

• It merges translations together from libraries, sub-modules and the main module.
• It also detects missing translations between languages.
• It also detects the translations changes in the main module compared to more inner other translations.

In i18n tables, each translation key begin with the module or library name, to not disturb other and future translations.
Where to place the translations:
A central module containing all translations would become too big and would always be in change for each correction of translations. That is not possible.
Each module or sub-module has its own /I18N submodule. See langs.
Proposed method to use them: Include 3 or 4 most used languages in the main central module and add some other languages for each case: project + language.
Then the versions.bind_modulesfunction follows these rules:
An alternative version can modify any translation of the normal version.
A main module can modify any translation from any submodule to adapt it to a new context.

Versions support

To activate the versions support of a module, start it with a definition of alternative versions of its sub-modules.
Tactic for versions numbers: They follow the format major.minor.release.
The major number is incremented when there's a big change in functionality.
Template or invoke arguments can replace soughtversions and knownversions.
In known versions, the first of each group of versions is the normal one and can replace any other if not available.
The versions support require() adequate versions of submodules, following known and sought versions, like Module:Box 2.
The versions support reports: versions used, errors, missing or replaced by normal ones.
Then Lua-coders can better understand what happens.
Any Lua-coder of main module can select versions of its submodules from internal arguments or from template arguments.
Each module or sub-module must document its version and date-time.
For the typical version description see convert a module as central.