Änderungs-Management

Transkript

1 Änderungs-Management Transfiniter Taschenrechner Claudio Kressibucher 2. August 2012 Dieses Dokument beschreibt die notwendigen (und einige optionale) Schritte, um Programm und Dokumentation konsistent zu halten die Qualität zu überprüfen Es richtet sich somit an Entwickler, die Änderungen an der bestehenden Version vornehmen wollen. 1

2 Inhaltsverzeichnis 1. Von den Quelldateien zur Build -Version 3 2. Kurzfassung der auszuführenden Schritte bei einer Änderung 3 3. Dokumentieren der Änderung (manuell) 4 4. Anpassen der Versions-Nummer (manuell) 5 5. Build-Prozess (automatisch) Die X Library Aktualisieren der Source-Dokumentation Konkatenieren und Minimieren Automatisierung mittels ant Entwicklung Logging Code-Qualität überprüfen Unit-Tests A. Voraussetzungen (benötigte Werkzeuge) 10 A.1. Konvertieren der Quelldateien in Build-Dateien A.2. Zusätzlich zum Testen (optional) B. Vorgeschlagener Workflow 11 2

3 1. Von den Quelldateien zur Build -Version Als rein Client-seitige Web-Applikation auf Basis von JavaScript, CSS und HTML muss grundsätzlich nichts kompiliert werden. Nach Herunterladen der Quelldateien kann src/ index.html im Browser geöffnet und das Programm ausgeführt werden. Änderungen in den Quelldateien (unter src) werden nach dem Neuladen im Browser sofort berücksichtigt. In den Unterverzeichnissen von src befinden sich mehrere JavaScript- und CSS-Dateien. Um ein effizienteres Laden zu ermöglichen, sollen diese zu einer einzigen JavaScript-Datei calc.js und einer einzigen CSS-Datei style.css zusammengefasst werden. Weiter sollen diese beiden Dateien anschliessend minimiert 1 werden. Mit diesen Anpassungen der Ressourcen geht die Anpassung der entsprechenden Referenzen in der Datei index.html, sowie in den beiden Manifest-Dateien 2 einher. Unter Build-Prozess werden im folgenden also alle Schritte verstanden, um aus den Quelldateien Ziel-Dateien zu erstellen, die obiger Beschreibung entsprechen. Eine zusätzliche Aufgabe dieses Prozesses ist die Erstellung einer Source-Dokumentation aus den Kommentaren der Quelldateien. Diesen Schritt kann man bei Bedarf auch einzeln ausführen, wenn man keine Build-Version des Programms erstellen möchte und die Quelldateien stattdessen direkt ausführen will. 2. Kurzfassung der auszuführenden Schritte bei einer Änderung Neben dem oben beschriebenen, automatisch ablaufendem Build-Prozess sind noch einige manuelle Schritte notwendig, um die Änderungen sauber zu dokumentieren. Das grundsätzliche Vorgehen bei Änderungen folgt diesem Schema: 1. Code-Änderungen in den Quelldateien vornehmen. Gegebenenfalls sind dabei auch die Kommentare anzupassen. 2. Änderungen in der bearbeiteten Quelldatei im einleitenden Block-Kommentar vermerken 3. Funktion und Qualität der Quelldateien überprüfen (Kapitel 6) 4. Versions-Nummer aktualisieren 5. Automatisierten Build-Prozess ausführen. Der Build-Prozess erstellt aus den Quellen im Verzeichnis src die Ziel-Dateien im Verzeichnis build. Bestandteile dieses Prozesses sind: Generieren eines Files, das die verwendeten Funktionen der X Library beinhaltet. Erstellen der Source-Dokumentation aus allen Quelldateien. Erstellen eines JavaScript-Files aus den einzelnen Source-Files und anschliessendes Minimieren. 1 Minimieren der Dateigrösse durch Entfernen von Kommentaren und Leerzeichen 2 In der Manifest-Datei werden die von der Applikation benötigten Ressourcen definiert. Der Application Cache verwendet diese Informationen um die benötigten Ressourcen lokal abzuspeichern, so dass die Applikation auch offline noch funktioniert. 3

4 Erstellen eines CSS-Files aus den einzelnen Source-Files und anschliessendes Minimieren. Kopieren der Manifest-Datei für die Build-Version 3 in das Build-Verzeichnis. Kopieren der Datei index.html in das Build-Verzeichnis und gleichzeitiges Anpassen der Referenzen 4 in dieser Datei. 6. Allenfalls testen der Build-Version. Diese Schritte sowohl die manuellen als auch der Build-Prozess werden nachfolgend etwas genauer beschrieben. Anschliessend folgen noch einige Informationen zu Testmöglichkeiten und zum Logging. Im Anhang A sind in übersichtlicher Form die Voraussetzungen für den Build-Prozess und für das Testen, konkret die dafür benötigten Tools, aufgelistet. Anhang B beschreibt den vorgeschlagenen Workflow, an dem man sich bei Änderungen orientieren kann. 3. Dokumentieren der Änderung (manuell) Änderungen der Funktion sind direkt im Code zu beschreiben. In JavaScript-Files sollte dazu die YUIDoc- Syntax (an JavaDoc angelehnt) verwendet werden. Jedes Source-File erhält einleitend einen Block /* * part of the Transfinite Ordinal Calculator * author: Claudio Kressibucher * license: GNU LGPL */ Dieser Block ist im bearbeiteten File mit dem Datum und dem Namen der bearbeitenden Person, sowie einer kurzen Beschreibung der Änderung zu erweitern. Beispiel: /* * part of the Transfinite Ordinal Calculator * author: Claudio Kressibucher * license: GNU LGPL * * edited: by Hans Muster (hans.muster@domain.org): * Method mynewmethod added */ 3 Unter src existieren zwei verschiedene Manifest-Dateien, manisfestdev.appcache referenziert die Quelldateien, manifestprod.appcache referenziert die Zieldateien. 4 zu JavaScript- und CSS-Files, sowie zur neuen Manifest-Datei manifestprod.appcache 4

5 4. Anpassen der Versions-Nummer (manuell) Weiter muss die (aus major- und minor-part bestehende) Versions-Nummer angepasst werden. Diese steht an verschiedenen Stellen, die konsistent gehalten werden müssen. Im File globals.js als Property config.projectversion In den Dateien reset.css und preamble.js im einleitenden Kommentar- Block 5. In der Datei index.html steht die Versions-Nummer im title-tag. In der ant-konfigurationsdatei build.xml wird die Verions-Nummer in Form von zwei Properties build.major und build.minor angegeben. Um dem Application Cache mitzuteilen, dass er die Dateien neu laden muss, ist es ausserdem nötig, die Manifest-Dateien manifestdev.appcache und manifestprod. appcache zu editieren 6. Für diesen Zweck wird dort allerdings nicht die Programm- Version genutzt, sondern das Änderungs-Datum und eine zusätzliche Nummer Build-Prozess (automatisch) Die in diesem Kapitel beschriebenen Schritte werden durch ant automatisiert. Es werden jedoch verschiedene Tools benötigt, deren Installation einmalig etwas Aufwand erfordern Die X Library Die X Library 8 ist eine Browser-Kompatibilitäts-Bibliothek. Sie stellt Funktionen zur Verfügung, die es ermöglichen, gewisse Grundoperationen auf verschiedenen Browsern einheitlich auszuführen. Die Bibliothek ist in viele einzelne Funktionen gegliedert, die bei Bedarf zu einer Datei zusammengefügt werden können. Diese Aufgabe 5 Die Versions-Nummer soll je einmal in den später generierten Ziel-Dateien calc.js und style.css stehen. Die erwähnten Dateien bilden jeweils den Anfang der entsprechenden Ziel-Datei. 6 Der Browser vergleicht das lokale Manifest-File mit dem des Servers. Unterscheiden sich diese, so wird das Manifest-File und die entsprechenden Ressourcen aktualisiert, ansonsten werden weiterhin die lokalen Ressourcen verwendet. Es wird zwar nur eine der beiden erwähnten Dateien benötigt (manifestdev. appcache wenn die Quelldateien verwendet werden, manifestprod.appcache bei Verwendung der minimierten Version), dennoch wird empfohlen, gleich beide zu aktualisieren, um gleiche Versionen zu erhalten. 7 Wenn der Application Cache aktualisiert werden muss, ändert man das Datum und setzt die Nummer auf 1 zurück. Für alle weiteren Aktualisierungen am gleichen Tag erhöht man dann die Nummer. Mit diesem Konzept kann man auch bei kleinen Änderungen, für die man keine neue Programm-Version einführen will, eine Aktualisierung des Application Cache erzwingen. 8 Informationen unter 5

6 das Parsen der Applikations-Sourcen und das Zusammenstellen der dort verwendeten Bibliotheks-Funktionen wird von dem X Aggregator 9 übernommen. Die resultierende Datei xlib.js wird anschliessend beim Konkatenieren genau wie die anderen JavaScript-Quellen miteinbezogen Aktualisieren der Source-Dokumentation Auf Basis der Quelldateien, genauer auf Basis der dort vorhandenen Kommentar- Blöcke, erstellt das Programm YUIDoc automatisch eine Dokumentation in HTML- Form. Dieser Schritt wird dringend empfohlen, damit die Source-Dokumentation mit den Quelldateien übereinstimmt. Auch wenn man keinen automatischen Build- Prozess durchführen möchte, sollte man bei Änderungen im Quelltext die Dokumentation aktualisieren (indem man YUIDoc manuell ausführt). YUIDoc 10 ist eine unter node.js 11 laufende JavaScript-Applikation. Die node.js-plattform kann darüber hinaus auch für das später (Kap. 6.2) beschriebene Test-Tool JsHint verwendet werden. Alternativ zur node.js-version gibt es noch eine Python-Version von YUIDoc, die aber nicht mehr gepflegt wird Konkatenieren und Minimieren Die einzelnen JavaScript- und CSS-Dateien müssen nun zusammengefügt und minimiert werden. Anschliessend müssen in index.html die Referenzen entsprechend angepasst werden. Das Konkatenieren der Einzeldateien wird durch ant selbst ausgeführt. Anschliessend wird das in Java geschriebene Programm YUICompressor 12 aufgerufen, welches die Minimierung der beiden Dateien calc.js und style. css durchführt. Die Anpassung der Referenzen in der HTML-Datei wird von DevToBuild 13 vorgenommen. Dieses kleine Programm löscht alle Zeilen zwischen den Kommentaren <!-- DEVELOPE_START --> und <!-- DEVELOPE_END --> (sowie auch die Kommentare selbst), und fügt die in den Kommentaren <!-- BUILD_START {HTML-Tags} BUILD_END --> eingeschlossenen HTML-Tags in das Dokument ein. 9 Auf der Webseite der Bibliothek als Linux- und als Windows-Programm verfügbar 10 Verfügbar unter 11 Informationen und Download unter 12 Download unter 13 DevToBuild wurde spezifisch für dieses Projekt erstellt. Die Java-Sourcen dazu sind auf der Projekt-Webseite unter Download verfügbar 6

7 Auf diese Weise werden die Referenzen zu den JavaScript- und CSS-Quelldateien, sowie zur Manifest-Datei manifestdev.appcache ersetzt durch Referenzen zu den Ziel-Dateien calc.js, style.css und manifestprod.appcache Automatisierung mittels ant Dem Projekt ist das schon erwähnte ant-konfigurations-file build.xml beigelegt, in dem die soeben beschriebenen Schritte definiert werden. Nach der Installation von node.js, X Aggregator, YUIDoc, YUICompressor und DevToBuild, sowie einem allfälligen Anpassen der Pfade in build.xml (und x-library-ant-macros.xml für den X Aggregator) werden die Schritte Generierung von xlib.js durch den X Aggregator Erstellen der Source-Dokumentation aus den Quellen Konkatenieren von JavaScript- und CSS-Dateien Minimieren der JavaScript- und der CSS-Datei Ändern der Referenzen in index.html Kopieren einiger Dateien aus dem Verzeichnis src in das Verzeichnis build/ htdocs automatisch ausgeführt. Als Ergebnis erhält man im Verzeichnis build zwei Verzeichnisse: doc Enthält die Dokumentation der Sourcen als HTML-Dokumente, htdocs Enthält die funktionsfähige Applikation, bestehend aus... index.html Mit angepassten Referenzen calc.js Der komplette JavaScript-Code der Applikation inklusive den Methoden der X Library style.css Dem kompletten Stylesheet der Applikation manifestprod.appcache Der Manifest-Datei für den Application Cache; referenziert die minimierten Ressourcen 7

8 .htaccess Wird für den Apache-Server benötigt, um das Server-seitige Caching zu deaktivieren 14 und um der Datei-Endung *.appcache den MIME-Type text/cache-manifest zuzuweisen. einigen Grafiken Ant wird von der Kommandozeile aufgerufen, wobei als Argument die Konfigurationsdatei build.xml angegeben werden muss: ant -file /path/to/build.xml Wenn ant aus dem Verzeichnis heraus ausgerufen wird, in dem sich build.xml befindet, dann kann auf die Angabe des build.xml-pfades verzichtet werden Entwicklung 6.1. Logging Um Änderungen vorzunehmen, empfiehlt es sich, einen geeigneten Log-Level einzustellen. Dadurch werden gewisse Meldungen an die Konsole, die mittlerweile in vielen (Desktop-)Browsern verfügbar ist, ausgegeben. Stellt der Browser kein console- Objekt zur Verfügung, so wird von der Applikation ein eigenes solches Objekt erzeugt. Die Meldungen werden dann als HTML unterhalb der Programm-Oberfläche ausgegeben. In der Datei globals.js kann man sowohl das Log-Level (über die Eigenschaft config.debug) sowie das Verhalten der Konsole (mittels config.useownconsole und config.prohibitownconsole) beeinflussen. Die Details der Einstellungs-Möglichkeiten sind als Kommentar in der Quelldatei beschrieben. Es ist darauf zu achten, dass in einer publizierten Version die Einstellung config.debug = 0 gesetzt ist Code-Qualität überprüfen Auch wenn dieser Schritt nicht zwingend nötig ist, empfiehlt es sich, die Code- Qualität regelmässig mit dem Tool JsHint 16 zu überprüfen 17. JsHint läuft auf verschiedenen Plattformen, u. a. auch auf dem bereits für YUIDoc verwendeten node.js. Im Verzeichnis tools/jshint befindet sich eine Konfigurtionsdatei jshint_ config.json, die dem Programm als Argument mitgegeben werden kann. Ein Aufruf aus dem Projekt-Wurzelverzeichnis Calc könnte bei Verwendung der Plattform 14 Das Caching wird vom Application Cache übernommen 15 weitere Informationen zur Ausführung von ant: 16 verfügbar unter 17 JavaScript-Quality-Tools wie JsHint überprüfen neben der eigentlichen syntaktischen Korrektheit die Einhaltung gewisser zusätzlicher Regeln, die zwar von der Sprach-Syntax nicht gefordert werden, die jedoch viele schwer auffindbare und unnötige Fehler verhindern können. 8

9 node.js etwa so aussehen 18 jshint --config./tools/jshint/jshint_config.json./src/js/ 6.3. Unit-Tests Eine weitere nicht unbedingt nötige, aber empfehlenswerte Möglichkeit, die korrekte Funktionsweise des Programms zu testen, ist die Ausführung der Unit-Tests. Es existieren Tests zur Überprüfung der Algorithmen der Ordinalzahl-Arithmetik. Somit empfiehlt es sich insbesondere nach Änderungen in der Klasse Calculation, diese Tests auszuführen. Die Unit-Tests werden von dem Java-Tool Js-Test-Driver 19 ausgeführt. Optional lässt sich mit dem Plugin CodeCoverage die Code-Abdeckung während der Ausführung der Unit-Tests protokollieren. Das Plugin speichert diese Daten in einer LCOV-Datei mit der Endung *.dat. Diese Daten können bei Bedarf visualisiert werden, z. B. unter Linux mit dem Tool genhtml 20. Für die Ausführung von Js-Test-Driver wird eine Konfigurationsdatei benötigt, in der man hauptsächlich die zu ladenden Quelldateien in der korrekten Reihenfolge definiert. Auch das CodeCoverage-Plugin muss in dieser Datei referenziert werden. Dem Projekt sind zwei solche Konfigurationsdateien beigelegt: Calc/test/jsTestDriver.conf führt die Tests auf den Quelldateien unter Calc/src/js/ aus. Calc/test/jsTestDriver_Build.conf führt die Tests auf den Build-Dateien unter Calc/build/htdocs/ aus. Die gewünschte Konfigurations-Datei wird beim Aufruf von Js-Test-Driver als Argument mitgegeben. Dem Projekt liegt ein Shell-Skript bei 21, welches die Tests, inklusive der Visualisierung der Daten in HTML-Files 22, ausführt. 18 Annahme: jshint ist in einem Verzeichnis installiert, das in der Umgebungsvariablen PATH definiert ist, und somit ohne Pfadangabe aufzufinden. 19 verfügbar unter 20 genhtml (Infos unter erstellt aus den LCOV-Daten eine Sammlung von HTML-Seiten. 21 unter tools/runtests.sh 22 das Plugin CodeCoverage muss dafür installiert und in der Js-Test-Driver-Konfigurationsdatei korrekt konfiguriert sein. Weiter muss das LCOV-Tool genhtml installiert sein. 9

10 A. Voraussetzungen (benötigte Werkzeuge) A.1. Konvertieren der Quelldateien in Build-Dateien Eine Java-Runtime-Umgebung. ant. Zum Konkatenieren der Quelldateien, zum Kopieren, Erstellen und Löschen von temporären Verzeichnissen, sowie zum Aufrufen aller weiteren nachfolgend genannten Hilfsprogramme. Deren Pfade müssen in der Datei build. xml definiert werden. X Aggregator 23. Zum Generieren von xlib.js. Es wird auch das entsprechende ant-build-file der Bibliothek (x-library-ant-macros.xml) genutzt. Standard- Pfad: tools/xlibtools/xag(.exe) YUIDoc. Zum Generieren der Source-Dokumentation. Standard-Pfad: tools/ yuidoc/bin/yuidoc (oder Systempfad für ausführbare Dateien) Die node.js-plattform zur Ausführung von YUIDoc. YUICompressor. Zur Minimierung der Dateien. Standard-Pfad: tools/yuicompressor/ yuicompressor-version.jar DevToBuild. Zum Ändern der Referenzen in index.html. Standard-Pfad: tools/ DevToBuild/DevToBuild.jar A.2. Zusätzlich zum Testen (optional) JsHint oder optional auch JsLint 24. Plattform zur Ausführung von JsHint 25 Js-Test-Driver Zur Ausführung der Unit-Tests. Standard-Pfad: tools/jstestdriver/ JsTestDriver-VERSION.jar Optional: CodeCoverage-Plugin. Standard-Pfad (konfiguriert in test/jstestdriver_ Build.conf und test/jstestdriver.conf): tools/jstestdriver/plugins/ coverage-version.jar Optional: Programm zur Visualisierung der LCOV-Daten, die vom CodeCoverage- Plugin erstellt werden. Bei Bedarf können die Test-Tools natürlich auch in den ant-prozess integriert werden. 23 xag für Linux, resp. xag.exe für Windows. Weitere Informationen unter cross-browser.com/x/docs/x_tools.php 24 Ein ähnliches Programm wie JsHint, siehe 25 Rhino, JavaScriptCore, WindowsScriptHost, oder Node.js. Siehe platforms/ 10

11 B. Vorgeschlagener Workflow 1. Überprüfen der Einstellungen in globals.js, insbesondere ob config.debug = 0 2. Überprüfen der Code-Qualität mit JsHint 3. Ausführen der Unit-Tests auf den Source-Files (src/js, Konfigurations-Datei test/jstestdriver.conf verwenden). 4. Anpassen von Datum und Nummer in beiden Manifest-Dateien. 5. Anpassen der Versions-Nummer in folgenden Dateien: Calc/build.xml (Properties build.major und build.minor) Calc/src/css/reset.css und Calc/src/js/preamble.js (Einleitende Kommentar-Blöcke) Calc/src/js/globals.js (Property config.projectversion) index.html (<title>-tag) 6. Im Projekt-Wurzelverzeichnis ant ausführen (Konfigurations-File build.xml) 7. Ausführen der Unit-Tests auf den Build-Files (build/htdocs/, Konfigurations- Datei test/jstestdriver_build.conf verwenden). 8. Optional: Bei Bedarf die Code-Abdeckung der Unit-Tests analysieren. (Dazu muss man erst mit einem LCOV-Tool die Daten visualisieren lassen). 9. Empfohlen: Calc/build/htdocs/index.html (Build-Version!) mit dem Browser öffnen und von Hand einige Testaktionen durchführen. Allenfalls auch anhand eines im Browser integrierten Entwicklungswerkzeugs prüfen, ob keine Fehler aufgetreten sind und ob alle Ressourcen geladen werden konnten. Resultat: Calc/build/doc Die Source-Dokumentation in HTML-Form. Calc/build/htdocs Das Wurzelverzeichnis der Applikation. 11