Wikiup:Lua/Entwicklung

Diese Seite beschreibt good practices, um Lua-Module zu entwickeln und sehr häufig eingebundene Module in den Artikeln wirksam werden zu lassen.

Erste Schritte

Die Sprache Lua ist recht gewöhnungsbedürftig. Obwohl sie beim oberflächlichen ersten Hinsehen trivial anmutet, entfaltet sie im Zusammenwirken mit der Wikisyntax und im Kontext einer echten Seiteneinbindung immer neue Überraschungen.

Mit Testvorlagen usw. in der Vorlagenspielwiese kann der Lua-Quellcode nach und nach in der Seitenvorschau entwickelt werden, ohne jede einzelne Version speichern zu müssen.

Es empfiehlt sich, am Anfang nicht zu viele Veränderungen gleichzeitig vorzunehmen; nicht auf einen Schlag Dutzende von Zeilen hinzuzufügen. Dadurch wären die Syntaxfehler nicht mehr zuzuordnen.

Nach einigen Wochen tut es aber nicht mehr weh.

Konsole und Seitenvorschau

Zur Handhabung siehe Hilfe:Lua/Quellcode und Vorschau.

Für die Gesamtwirkung der Modul-Ergebnisse ist die Vorschau-Funktion wichtiger, insbesondere mit der im nächsten Abschnitt dargestellten Testseite.

Testseite

Zu jedem produktiven Modul ist zwingend eine Testseite in Wikisyntax erforderlich. Sie erlaubt einen routinemäßigen Schnelltest, ob das Modul noch prinzipiell in ordnungsgemäßem Zustand ist.

Es sind nach Funktionen gegliedert die typischen Vorlageneinbindungen und dafür das erwartete Ergebnis und das momentane Resultat aus dem Lua-Modul gegenüberzustellen, so dass sie unmittelbar und übersichtlich verglichen werden können.

Gleichzeitig kann die Testseite als Bestandteil der Dokumentation alle diese Beispielfälle zur Veranschaulichung nutzen.

Beispiele: URLutil und TemplatePar.

Weder Testseiten noch ein unit test garantieren Fehlerfreiheit. Sie können nur so zuverlässig sein wie die Auswahl an Kombinationen. Alle gängigen Programmpfade sollten abgedeckt sein, und auch die erwarteten Fehlersituationen in der späteren Nutzung (Pflichtparameter nicht angegeben, ungeeignete Werte, Leerzeichen um den Wert oder als alleiniger Wert, falsche Parameternamen).

unit test

Dieser „Modultest“ ist dazu geeignet, schnell und automatisiert viele Ergebnisse zu überprüfen.

• Relativ leicht ist es, sich selbst eine Abfolge zu schreiben, die Ergebnisse von Funktionen für Module überprüft; also solche, die nicht mittels #invoke aufgerufen werden:
  • Tabelle anlegen, deren jedes Element eine Abfolge ist von Funktionsname, Resultat, Parameterzuweisungen.
  • Tabelle durchlaufen und die jewelige Funktion aufrufen; Fehlermeldung, falls aktuelles Ergebnis nicht mit dem Resultat übereinstimmt.
• Das Module:UnitTests aus der englischsprachigen Wikipedia unterstützt zunächst dabei, eine Einbindung mittels #invoke zu prüfen. Weil aber beliebiger Wikitext gegen das erwartete Ergebnis getestet werden kann, eignet sich dieses Verfahren sogar für Vorlagen, an denen noch nicht einmal ein Modul beteiligt sein muss.
• Etwas effizienter ginge das für Einzelvorlagen mit frame:expandTemplate.
• Wenn das Ergebnis auch von Namensräumen oder Seitennamen abhängt, wird die Simulation schwierig. Dann empfiehlt sich beta.

beta

Auf dem β-dewiki gibt es eine Simulation der deutschsprachigen Wikipedia.

• Alle Umgebungseigenschaften einschließlich der Namen der Namensräume und sonstige Einstellungen stimmen überein.
• Einige Artikel, Vorlagen und sonstige Seiten können dorthin kopiert und der echte Betrieb erprobt werden.
• Die Software ist ihrer Zeit um einige Wochen voraus. Die Grundausstattung mit den Systemnachrichten stammt von Anfang 2012.
• Standard-Modulbibliotheken werden dort verfügbar sein, könnten aber selbst gerade einen Entwicklungsschub erfahren und etwas mucken.
• Auf der echten Wikipedia können die Administratoren angefragt werden, wenn es etwas zu tun gibt.
• Weil Beta ein Erprobungsprojekt ist, sind gelegentlich Server-Fehlermeldungen sichtbar, die auf einem normalen Projekt nicht erscheinen. Dies kann ignoriert werden. Im Lauf des Jahres 2013 wird die Funktionalität weiter ausgebaut werden.

Für Module, die noch im Alpha-Stadium bereits in einer begrenzten Anzahl von Seiten testweise produktiv erprobt werden, kann man noch nicht freigegebenen Code ausschalten, indem eine für das Modul globale Variable gesetzt wird:

local debugging = ( mw.site.server == "//de.wikipedia.beta.wmflabs.org" )

Die noch nicht ausgereifte, verfeinerte Funktionalität kann damit vorläufig durch erprobte, einfachere und robustere Zeichenketten ausgetauscht werden, falls es erforderlich ist, ein bereits produktiv eingesetztes Modul bereitzuhalten.

Review

• Bevor man mit einem neuen Modul projektweit auftritt und dies in Tausende von Seiten einbindet, sollte man sein Konzept zur Diskussion stellen. Dafür bietet sich die Lua-Werkstatt an.
• Aus anderer Perspektive fallen auch andere Gesichtspunkte auf.
• Schwachstellen, Verständlichkeit, konzeptionelle Mängel bemerkt man im eigenen Werk zuletzt (Betriebsblindheit).
• Kollegen haben Anregungen und Ideen, wie mit einem Parameter mehr oder einer weiteren Funktion das Anwendungsgebiet und die Nutzungsmöglichkeiten deutlich erweitert werden können.

Häufig eingebundene Module

Solange ein Modul nur in ein paar Hundert Seiten eingebunden ist, insbesondere nicht in Artikeln wirksam wird, kann man noch etwas lockerer die echte Version direkt bearbeiten.

Über die Nutzung in mehreren Vorlagen und durch andere Module können bei projektweiten Bibliotheksmodulen Zehntausende und Hunderttausende von Seiten von der Änderung betroffen sein.

In diesem Fall ist in einer Test-Umgebung eine Entwicklungsversion erforderlich, an der experimentiert werden kann.

Die Produktivversionen sollten so selten wie möglich geändert werden. Entweder muss eine sichtbare negative Auswirkung in den einbindenden Seiten beseitigt werden, oder es ist nach Abschluss einer Testphase auf lange Zeit keine Änderung mehr zu erwarten und neue Funktionalität bereitzustellen. Kleinere Änderungen, etwa eine etwas effizientere Gestaltung eines Statements oder womöglich nur in einem Kommentar, sollten in der Test- und Entwicklungsversion gesammelt werden und dies wird dann bei einem wichtigen Anlass mit übernommen.

Die normale Versionsgeschichte einer Seite ist bei zweigleisiger Entwicklung nicht aussagekräftig. Um beim Kopieren zwischen ausgetesteter Version und Produktivversion nicht durcheinanderzukommen, empfiehlt es sich, im Kommentar des Seitenkopfes das Datum zu vermerken.

Update der Produktivversion

Zuerst in einem Rutsch alle möglicherweise aktualisierten Vorlagen in die produktiven Seiten kopieren; sofort danach für den in das Bearbeitungsfeld kopierten aktualisierten Quelltext des Lua-Moduls mit der Testseite einen letzten Bedside-Test vornehmen, bevor gespeichert wird. Es kann einem immer mal passieren, dass man sich beim C&P vertut, die falsche Variante kopiert hat oder durch einen verirrten Mausklick ein Laufzeitfehler bewirkt wird. Außerdem die diffpage checken, ob die Änderungen plausibel erscheinen.

Es gilt:

Ein Wurf, ein Treffer.

Mögliche Testumgebungen

{{Wikipedia:Lua/Erprobung}}