« Module:Centralizer:CentralDescription.xml » : différence entre les versions

Contenu supprimé Contenu ajouté
m Rical a déplacé la page Discussion module:Centralizer vers Module:Centralizer:CentralDescription.xml : Add a new Description of Central modules
Add a new Description of Central modules
 
Ligne 1 :
<!-- CentralDescription.xml
<div style="float:right;margin-left:1em;"> __TOC__ </div>
Save as CentralDescription.xml CentralDescription update Central modules in brief 20190338.xml
-----------date|-------------- File --------------Title ---------- typical length ------|----------max| DODO
end -- res = res .. p.init_central_module(frame, mode_name, known_arguments, options_for_modes, QITEM) replaces function Central.init(...
update CentralDescription.xml synchronously at the same times as ModuleCentralizer
-->
 
<!-- Doc update at 2018-11-29T12:26:00 UTC ISO 8601 TODOC -->
=== Documentations and live examples ===
<!-- { "20190128", "20190129", "todo", "Rical", "S190128rlv", "After 'Begin' Fully update CentralDescription.xml Tactic, func names ...", }, -->
<!-- { "20181201", "20181203", "todo", "Rical", "S181124uCM", "For 'Begin' update CentralDescription.xml Guideline to Tactic, func names ..." }, -->
 
<center> <span style="color:red;" >This documentaion is only in draft state.</span> </center>
* The main present [[s:fr:Module:Central|Module:Central]] installs central libraries. It is in French Wikisource.
<center> <span style="color:red;" >Some parts are empty or missing</span> </center>
<div style="float:{{dir|{{pagelang}}|left|right}}; margin-{{dir|{{pagelang}}|right|left}}:1em" >__TOC__</div>
 
=== 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 [[s:fr:Centralizer:Module/I18N|Centralizer:Module/I18N]] is made to contain available translations.
Add, or adjust, a new langage need only to change this Centralizer:Module/I18N.
<br>They are also multi languages as able to use in one run the content language, the page language and the user langage.
<br>They are multi wikis using the future Phabricator task [[phab:T121470|T121470]] "Begin T121470 Central Global Repository for Templates, Lua modules, and Gadgets"
<br>This task permit to use in local any central Lua module.
<br>The Lua part of central modules support contains 10 libraries used by central modules.
<br>The first test is dated of Xmas 2013.
<br>On january 2019 they are based on 10 libraries installed by the [[s:fr:Module:Centralizer|Module:Centralizer]] which must be used in each wiki/language in the last version.
<br>These continue until they become parts of <code>Scribunto</code>.
<br>
<br>In this document, <b>Library:</b> is not a namespace, only a way to shortly express that an object is understood as a library.
<br>Each new language need only to translate 300 short texts.
<br>See <code>[[:#How to convert a module as central|convert a module as central]]</code>.
<br>
<br>The central system permits to convert any module as central.
<br>Central libraries are intimately dependent of each other. Examples: the <code>Library:versions</code> installs others and the <code>Library:viewers</code> 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.
<br>Errors in them are corrected in one wiki/language but continue in others.
<br>Small wikis do not have Lua-coders to translate them and can not use them.
<br>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.
<br>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 [[mw:Extension:Scribunto|Scribunto]] extension.
<br>See also the Tactics [[:mw:Manual:Developing libraries|Manual:Developing libraries]].
* [[s:fr:MediaWiki:Scribunto/Central guideline|Guideline of central modules]].
* [[s:fr:MediaWiki:Scribunto/Central_modules_reference_manual|MediaWiki:Scribunto/Central modules reference manual]]
* The main present [[s:fr:Module:Central-s-fr|Module:Central]] installs central libraries. It is in French Wikisource.
* Template example: [[s:fr:Modèle:Central|Modèle:Central]]
* Main module example: [[s:fr:Module:Author3|Module:Author3]]
* AuthorExample of module examplefor an author: [[s:fr:Utilisateur:Rical/Victor_Hugo|fr:Utilisateur:Rical/Victor_Hugo]]
* Small wiki example of central tests: [[w:vi:Mô_đun:CentralizerCentral-w-vi/tài_liệu|Vietnamese Module Documentation]]
* Translations servicesupport: [https://translatewiki.net/wiki/Translating:MediaWiki Translating:MediaWiki], and [https://translatewiki.net/wiki/Translating:Group_statistics its statistics].
* [[mw:Extension:Scribunto|Scribunto extension]]
* [[mw:Extension:Wikibase Client/Lua|Extension:Wikibase Client/Lua]]
The Phabricator task [[phab:T20180527|T20180527]] "Begin to use central modules", invite you to cooperate about the transfert of know-how.
* [[s:fr:MediaWiki:Scribunto/Central_modules_reference_manual|MediaWiki:Scribunto/Central modules reference manual]]
<br>During this phase Lua-coders need to cooperate.
* Examples of modules and their uses in live demo <b>in debug phase</b>:
<br>They could dialogate in [[s:fr:Discussion MediaWiki:Scribunto/Central guideline/Discussion|Discussion MediaWiki:Scribunto/Central guideline]].
* [[Module:Centralizer]], [[Module:Centralizer/Documentation]], [[Module:Author3]]
<!-- TODOC up to which line has this document been updated? ▼ }} -->
* [[Utilisateur:Rical/Victor_Hugo]] with tests.
 
=== Tests pages ===
Central libraries: [[s:fr:Module:Central-s-fr|Module:Central]].
<br>Simple examples of uses: [[s:fr:Module:Central-s-fr/Documentation|Module:Central/Documentation]]
<br>Full example: [[s:fr:Utilisateur:Rical/Victor_Hugo|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.
 
=== DocStability with item = docitemTactic ===
Some questions are especially important for all developers in the early phase of the deployment of central modules.
<nowiki>
<br>Libraries and functions names must be stable before a large deployment to reduce the renaming of them.
{{Centralizer|doc|dockey=versions_support_desk_title|docitem=Q535}}</nowiki>
<br>That could imply heavy corrections after the begin phase.
{{Centralizer|doc|dockey=versions_support_desk_title|docitem=Q535}}
<br>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 <code>table</code> library from the Lua language, to avoid ambiguities.
: To enhance <code>Scribunto</code> <code>table</code>, we could write: <code>lua_table = table</code>.
* 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 <code>"Module with internal error"</code> and <code>"Module with usage error"</code> 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 <code>args</code> separed from the existing library <code>modes</code>, to easier identity the main job of each function?
 
===Stability tasks ===
=== Doc with function from string ===
<!-- * Same tests of functions are available for MediaWiki testframework and for Lua-coders in tests mode. -->
<nowiki>
* The [[#versions|versions]] library installs sought sub-modules using versions support.
{{Centralizer|doc|dockey=modes_get_args_report_title|docfunc=modes.get_args_report}}</nowiki>
* [[#Dropbox|Drop boxes]] and [[#tableview|tables views]] help to easy format new tests.
{{Centralizer|doc|dockey=modes_get_args_report_title|docfunc=modes.get_args_report}}
* The [[#activity|activity]] library help to manage sub-tasks and phabricator tasks, between Lua-coders, projects and languages.
* The [[#tracker|tracker]] object supports parametrable track objects to help to debug the Lua code.
* The [[#events|events]] library formats events as errors, warnings and categories.<!--
* The [[#testframework|testframework]] library reports differencies in attended results from functions. It reports recursively at tests cases level for groups of groups of tests cases.
* The deprecated functions support the detection of their uses.
* Any detail in any page can crash whole the page. An antiCrash function can protect against that fail. -->
* 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 <code>[[:#viewers.save_restore_balance_report|viewers.save_restore_balance_report]]</code> checks and reports known couples of save and restore global configurations to reduce interferences between tests.
 
=== Central normalsupports read mode ===
The central system permit some new supports.
<nowiki>
{{Centralizer|read|QITEM=Q535}}</nowiki>
{{Centralizer|read|QITEM=Q535}}
 
=== Languages support ===
=== Edit mode example for English user / French project ===
Central modules support translations in many languages, using i18n tables.
<nowiki>
<br>They support also the content, page and user languages.
{{Centralizer|edit|contentlang=es|pagelang=fr|userlang=en|QITEM=Q8023}}</nowiki>
<br>The system can also suggest a default local language depending where the module is used.
{{Centralizer|edit|contentlang=es|pagelang=fr|userlang=en|QITEM=Q8023}}
<br>For these goals, central modules get these languages from the system, modes, options, arguments and tests cases.
 
=== Translations support ===
=== Edit mode example for Spanish user / French project ===
The [[#langs|langs]] library supports i18n translations.
<nowiki>
* It merges translations together from libraries, sub-modules and the main module.
{{Centralizer|edit|contentlang=en|pagelang=fr|userlang=es|itemid=Q34743}}</nowiki>
* It also detects missing translations between languages.
{{Centralizer|edit|contentlang=en|pagelang=fr|userlang=es|itemid=Q34743}}
* 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.
<br>Where to place the translations:
<br>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.
<br>Each module or sub-module has its own <code>/I18N</code> submodule. See <code>[[:#langs|langs]]</code>.
<br>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.
<br>Then the <code>[[:#versions.bind_modules|versions.bind_modules]]</code>function follows these rules:
<br>An alternative version can modify any translation of the normal version.
<br>A main module can modify any translation from any submodule to adapt it to a new context.
 
=== Versions support ===
=== Edit mode example for French user / English project ===
To activate the versions support of a module, start it with a definition of alternative versions of its sub-modules.
<nowiki>
<br>Tactic for versions numbers: They follow the format major.minor.release.
{{Centralizer|edit|contentlang=es|pagelang=en|userlang=fr|QITEM=Q868}}</nowiki>
<br>The major number is incremented when there's a big change in functionality.
{{Centralizer|edit|contentlang=es|pagelang=en|userlang=fr|QITEM=Q868}}
<br>Template or invoke arguments can replace <code>soughtversions</code> and <code>knownversions</code>.
<br>In known versions, the first of each group of versions is the <code>normal</code> one and can replace any other if not available.
<br>The versions support <code>require()</code> adequate versions of submodules, following known and sought versions, like <code>Module:Box 2</code>.
<br>The versions support reports: versions used, errors, missing or replaced by normal ones.
<br>Then Lua-coders can better understand what happens.
<br>Any Lua-coder of main module can select versions of its submodules from internal arguments or from template arguments.
<br>Each module or sub-module must document its version and date-time.
<br>For the typical version description see <code>[[:#How to convert a module as central|convert a module as central]]</code>.
 
<!-- TODOC up to which line has this document been updated? ▼ }} -->
=== Tests mode example ===
<nowiki>
{{Centralizer|tests|itemid=Q535}}</nowiki>
{{Centralizer|tests|itemid=Q535}}