Help:Extension:Translate/Developer guide/nl

<translate> Documentation for <tvar|ext>Extension:Translate/nl</></translate>

<translate> Translators</translate> (<translate> main help page</translate> )

<translate> Translation administrators</translate>

<translate> Sysadmins and developers</translate>

<translate> Translate this template</translate>

De extensie Translate is een grote extensie met honderden classes. Deze pagina biedt begeleiding voor ontwikkelaars die willen werken aan de code. Na het lezen van deze pagina en de gelinkte documenten zult u beter begrijpen hoe code in Translate is georganiseerd en welke speciale conventies worden gebruikt. Algemene ontwikkelingsbeleid van MediaWiki, coderingsconventies en het gebruik van tools als Gerrit en Phabricator worden hier niet behandeld. U dient bekend te zijn met deze onderwerpen en wanneer deze betrekking hebben op Translate, deze punten worden hier niet worden herhaald.

De extensie Translate ondergaat veel grote migraties tegelijkertijd. Hier worden de belangrijkste migraties vermeld die aan de gang zijn en wordt beschreven welke stijlvoorkeur wordt gegeven aan de nieuwe code. In het algemeen is het beter om bij het wijzigen van bestaande code bij te houden aan de huidige stijl en migraties afzonderlijk te doen. Sommige kleinere correcties zijn goed om te doen bij het wijzigen van code.

Namespace migratie

We zijn bezig met het migreren van alle code van Translate onder de namespace \MediaWiki\Extension\Translate. Alle code met een namespace wordt geplaatst in de map src/. Alle nieuwe PHP-bestanden moeten in een passende namespace worden geplaatst. Zie Extension:Translate/Namespaces voor informatie over welke namespaces beschikbaar zijn. Namespaces worden georganiseerd volgens domein, en niet op functie. Vermijd afkortingen in namespaces en class-names. Legacy code staat in de repository root en verschillende submappen.

In Gerrit berekent SonarCube de code review dekking alleen voor code onder de map src/.

Splitsen van tests in integratie- en unittests

Eerder was er geen onderscheid tussen integratie- en eenheidstests. Voor de nieuwe code moeten de eenheidstests het belangrijkste type test zijn. Eenheidstesten worden in de map tests/phpunit/unit geplaatst die overeenkomt met de namespace lay-out. Er is een Makefile in die map om alle of delen van de eenheidstests gemakkelijk te laten uitvoeren tijdens het ontwikkelen.

Type declaraties en commentaar

Alle nieuwe code moet zowel parameters declareren als returntypes geven. Bovendien moeten er strikt op type worden gecontroleerd door het inschakelen van declare( strict_types = 1 );.

Dankzij type declaraties zijn de meeste functie- en methodecommentaren nu overbodig, omdat ze alleen de parametersnamen en -typen herhalen. Om deze reden worden de linter controles voor ontbrekende parameters of returntypes uitgeschakeld voor code onder src/ en tests/, wat ongeveer correleert met plaatsen met type declaraties. Voor deze code moet u geen overbodige documentatie toevoegen tenzij deze een extra waarde biedt. Een van deze voorbeelden is het geven van nauwkeuriger tips voor arraytypen, bijvoorbeeld:

class UserManager {
  /** @return User[] */
  public function getAllUsers(): array { ... }
}

Zoals hierboven aangegeven is, gebruik voor opmerkingen met slechts één tag of een regel beschrijving met ook die syntaxis van een commentaarregel.

Er is geen sprake van een linter over tussenruimte om : in returntype declaraties. Totdat dit de norm wordt, gebruik de geïllustreerde stijl: geen spatie ervoor, één spatie erna.

Constructor afhankelijke injectie

De nieuwe code moet alle afhankelijkheden via de constructor laten injecteren. In sommige gevallen is dit nog niet mogelijk, omdat sommige diensten alleen beschikbaar zijn in de meest recente versie van MediaWiki en het gebrek aan ondersteuning voor ObjectFactory voor sommige soorten classes zoals jobs en onderhoudsscripts. Voor nieuwe code moeten alle afhankelijkheden van de class-constructeur (of het belangrijkste toegangspunt van de class) worden geplaatst om in de toekomst eenvoudig te migreren naar de injectie via de constructor.

Onderhoudscripten kunnen geen code gebruiken die PHP-autoloader vereist, dus alle afhankelijkheden kunnen alleen worden verklaard in de methode execute, niet in de constructor.

File header

Voor nieuwe code hebben we de volgende minimalistische header gekozen:

<?php
declare( strict_types = 1 );

namespace Example;

use OtherStuff;

/**
 * Class description.
 * @author Your name
 * @license GPL-2.0-or-later
 * @since 2020.06
 */
class ExampleClass {
  /** @return User[] */
  public function getAllUsers(): array { ... }
}

Als u uw auteursrecht meer expliciet wilt bevestigen, kunt u ook de tag @copyright toevoegen.

Ontraden en versienummers

Wanneer u de code van Translate op een achterwaartse onverenigbare manier wijzigt, moet u https://codesearch.wmcloud.org/search/ controleren voor gebruikers van de code. Bekende gebruikers zijn TwnMainPage, TranslateSVG, CentralNotice, MassMessage en een hoop spullen in de translatewiki-repository.

U kunt de faciliteiten voor ontraden gebruiken die worden aangeboden door MediaWiki core, inclusief de tag @deprecated en de harde vorm van ontraden wfDeprecated(). Als er geen bekende gebruikers van de code zijn, is het oké om deze op een achterwaarts incompatibele manier te wijzigen zonder ontraden, tenzij deze expliciet is gemarkeerd als stabiel (zie Stabiel interfacebeleid). Code die als stabiel wordt genoemd moet ten minste voor één release van MediaWiki Language Extension Bundle/nl (MLEB) hard worden ontraden.

MediaWiki kernversie nummers zijn zinloos in de context van Translate, omdat Translate altijd meerdere MediaWiki-versies ondersteunt. Translate zelf gebruikt de stijl YYYY.MM van versies (als onderdeel van MLEB). Nieuwe classes en methoden moeten worden geannoteerd met @since YYYY.MM-tags.