Help:Extension:Translate/Developer guide/cs

Rozšíření Translate je velké rozšíření se stovkami tříd. Tato stránka poskytuje pokyny pro vývojáře, kteří chtějí pracovat na kódu. Po přečtení této stránky a propojených dokumentů lépe pochopíte, jak je kód v Translate organizován a jaké speciální konvence se používají. Obecné zásady vývoje MediaWiki, konvence kódování a používání nástrojů jako Gerrit a Phabricator jsou mimo rozsah této statě. Předpokládá se, že tato témata znáte, a pokud se týkají Translate, nebudou se zde opakovat.

Rozšíření Translate prochází mnoha velkými migracemi současně. Zde uvádíme hlavní migrace, které právě probíhají, a podrobně popisujeme, který styl je preferován pro nový kód. Obecně platí, že při úpravách stávajícího kódu je lepší držet se aktuálního stylu a migrace provádět samostatně. Při osahávání kódu je v pořádku provést některá drobná čištění.

Migrace jmenného prostoru
Právě probíhá migrace veškerého kódu Translate pod jmenným prostorem. Veškerý jmenný kód je umístěn v adresáři. Všechny nové soubory PHP by měly být umístěny do vhodného jmenného prostoru. Informace o tom, které jmenné prostory budou k dispozici, najdete v. Jmenné prostory jsou organizovány podle domény, nikoli podle funkce. Ve jmenných prostorech a názvech tříd je potřebné se vyhnout zkratkám. Starší kód je v kořenovém adresáři úložiště a různých podadresářích.

Rozdělení testů na integrační a jednotkové
Dříve se nerozlišovalo mezi integračními a jednotkovými testy. U nového kódu by hlavním typem testů měly být jednotkové testy. Testy jednotek jsou umístěny v adresáři, který odpovídá rozložení jmenného prostoru. V tomto adresáři je Makefile pro snadné spuštění všech nebo částí testů jednotek během vývoje.

Type declarations and comments
All new code should declare both parameter and return types. In addition strict types should be enabled using.

Thanks to type declarations, most function and method comments are now redundant, as they would only repeat the parameter names and types. For this reason, linter checks for missing parameter or return type declarations are disabled for code under  and , which roughly correlate with places using type declarations. For this code, do not add redundant documentation unless it provides additional value. One such example is to provide more accurate type hints for array types, for example:

As illustrated above, for comments having only one tag or one line description, do use the one line comment syntax as well.

Constructor dependency injection
New code should have all its dependencies injected via constructor. In some cases this is not yet possible, due to some services only being available in the most recent version of MediaWiki as well lack of ObjectFactory support for some type of classes like jobs and maintenance scripts. For such new code, place all dependencies on the class constructor (or main entry point to the class) to easy migration to constructor dependency injection in the future.

File header
For new code, we have chosen the following minimalistic header:

If you wish to assert your copyright more explicitly, you can optionally add @copyright tag as well.

Deprecation and version numbers
When changing Translate code in backwards incompatible ways, do check https://codesearch.wmcloud.org/search/ for any users of the code. Known users are TwnMainPage, TranslateSVG, CentralNotice, MassMessage and bunch of stuff in the translatewiki repository.

You can use the deprecation facilities provided by MediaWiki core, including the @deprecated tag and wfDeprecated hard deprecation. If there are no known users of the code, it is okay to change it in backwards incompatible way without deprecation, unless it is explicitly marked as stable (See Stable interface policy). Code marked as stable should be hard-deprecated at least for one MLEB release.

MediaWiki core version numbers are meaningless in the context of Translate, as Translate always supports multiple MediaWiki releases. Translate itself uses YYYY.MM style versioning (as part of MLEB). New classes and methods should be annotated with @since YYYY.MM tags.