Versiebeheer: releases en revisies

Hoe werkt de SVN repository?

De SVN repository bevat twee directories: development/ met de actuele ontwikkelversie, en release/ met daarin stabiele releases van OpenAC. De versies onder release hebben namen v1.nnn/ (uiteindelijk ook v2.nnn/).

De AC's kunnen zelf wijzigingen in hun adapataties inleveren. Ze doen dit in de regel in de nieuwste release. Wanneer een AC een wijziging heeft ingeleverd, is dit te zien in de timeline van TRAC. Die houden we als ontwikkelaars dus nauwlettend in de gaten. Wekelijks worden wijzigingen door centra ingeleverd overgenomen in de development-tak. Als centra een oudere release in gebruik hebben, worden wijzigingen ook in de nieuwere releases overgenomen. Wanneer een centrum een wijzing indient en er is al een nieuwe release, krijgt men een waarschuwing dat de ingeleverde zaken niet automatisch beschikbaar zijn in de nieuwe release.

Wijzigingen die in een release worden ingeleverd, moeten via een SVN merge worden opgenomen in de ontwikkeltak.

Wizigingen overnemen

Het meest gemakkelijke is om wijzigingen naar "voren" over te nemen: van een release versie naar nieuwere release versies, of over naar development. Omdat dit regelmatig moet gebeuren is het het meest gemakkelijk om het automatisch met SVN tools te doen.

svn merge, sinds SVN 1.6, houdt bij welke wijzigingen zijn overgenomen. Daardoor voorkom je dat wijzigingen meer dan een keer overgenomen worden, en het wordt ook vrij makkelijk:

svn pg svn:mergeinfo development
svn merge -r NNN:HEAD release/v1.222 development/
svn commit -m "OVERNEMEN: v1.222 -> development NNN t/m MMM"

Met het eerste commando vraag je de mergeinfo op van SVN. Omdat er sommige oude revisies nooit gemerged zijn op een heldere manier, willen we die ook niet meer overnemen. Kijk wat de laatst-gemergede revisie is (in dit geval gaan we v1.222 naar development mergen, dus zoek de uitvoer regel met release/v1.222 en onthoud de meest recente revisie daar. Zeg dat NNN=r19183, bijvoorbeeld.

Vervolgens doen we de merge zelf. Veranderingen vanaf revisie NNN worden overgenomen van v1.222 naar development. Hierbij kunnen conflicts ontstaan. Los die op.

Tot slot met de commit worden de nieuw gemergede revisies als een enkele commit doorgegeven. Merk vervolgens op dat de svn:mergeinfo veranderd is.

Backports

Het is ook mogelijk om veranderingen over te nemen van nieuwere versies naar oude, de zogenaamde backports. Dit gebeurt als er belangrijke functionaliteit ontwikkeld wordt, zeg in development, dat vervolgens tussen twee releases door uit moet komen, of als er ingewikkelde bugfixes moeten worden overgenomen.

svn merge werkt ook van development naar andere branches, maar in het geval van backports is het vaak handig om specifieke commits over te nemen. Gebruik dan -c NNN in plaats van -r NNN:HEAD om precies een revisie NNN over te nemen. Welke revisies over te nemen kan je lezen uit de timeline van OpenAC of uit svn log.

Planning van een OpenAC release

• De releasedatum is de datum dat de acceptatieversie wordt aangemaakt door de development-branch te kopiëren naar een release-branch. De releasedata vallen in principe op 31-3, 30-6, 25-9 en 15-12 (4x per jaar).
• 5e week voor releasedatum: scope bepalen, ontwerpjes maken
• 4e en 3e week voor releasedatum: bespreken ontwerpjes voor de grotere tickets, tickets afwerken
• 2e week voor releasedatum: testen (en soms nog wat losse eindjes ontwikkelwerk), 2 pilot-AC's zoeken
• week voor releasedatum: documenteren, changes overnemen en live (zie hieronder)
• week na releasedatum: test bij 2 pilot-AC's, changes overnemen, bericht productieversie live

Testen en maken van een OpenAC release

Je zit in een werkkopie van de tak 'development'. Doe nu de volgende stappen:

• Ga op de TRAC-website onder "Timeline" naar de vorige release, en loop zorgvuldig de changesets na die sindsdien zijn ingevoerd, draai eventueel een DIFF. Dit gebeurt elke week maar moet vlak voor een release nog een keer worden herhaald, zodat op het moment dat de release note uitkomt, alle wijzigingen zijn overgenomen. Wat men daarna inlevert, moet men zelf weten (versiebeheer waarschuwt dan ook).
• Controleer of alle wijzigingen in de loop van de vorige release zijn overgenomen: development/bin/adaptatie-diff v1.XXX development (vergelijk laatste versie met development). Loop de diff door op vergeten change sets.
• Draai de unit tests en fix zonodig
• Loop het test script? door
• Merge door AC's gemaakte fixes op de vorige release in de development-tak
• Test de wijzigingen zonodig
• svn commit om de wijzigingen uit de merge in te leveren
• Werk VERSIES.txt bij door de releasedatum aan de laatste versie toe te voegen en de omschrijving af te maken
• Draai bin/clean en commit eventuele bestanden die nog geen eol-style LF hadden
• Draai nog 1x de unit tests
• svn commit
• Draai bin/release 1.XXX om development te kopiëren naar de nieuwe release in SVN
• Maak de adaptatiemap in de nieuwe release schrijfbaar voor centra door 3 regels te kopiëren in /usr/local/apache1/svn/etc/permissions
• Stuur een release-bericht naar openac@…. Denk daarbij goed na welke migraties er allemaal gebeuren bij deze nieuwe versie.

Maken van een nieuwe starter kit

De starter kit is in essentie een self-extracting ZIP van een release branch van OpenAC. Dit zijn de stappen die je moet doorlopen om een starter kit te maken.

• Check de release uit waarvan de starterkit moet worden gemaakt.
• Zorg dat de volgende elementen in de directory aanwezig zijn: directory Python25, en de 4 DLLs msvcpp71.dll, python25.dll, pythoncom25.dll en pywintypes25.dll.
• Draai ./bin/clean. Dit ruimt tempfiles op en zet permissies goed, maar kan ook wijzigingen maken in bestanden. Doe een svn status en als er wijzigingen zijn, deze eerst committen.
• Draai ./bin/makezip. Dit maakt een complete ZIP die goed door windows kan worden uitgepakt.
• De zip is ongeveer 100MB.
• Gebruik EnZIP voor het maken van de EXE: rechtermuis op starterkit.zip -> open with Enzip -> Create self extractor
• Bij Message Box: nee, we willen geen message box.
• Bij Folder: "OpenAC"
• Title Caption: "OpenAC installatie"
• Command: icon.bat
• Selecteer het icon-bestand images/OpenAC-128x128.ico
• In het laatste scherm geen opties veranderen
• Upload het bestand naar Downloads op de TRAC site
• Pas de links aan op de wiki-homepage en in de installatiehandleiding, zodat deze wijzen naar de meest recente starter kit.

Online documentatie genereren

Infrastructuur en werking

De benodigdheden voor het genereren van de online documentatie staan op de server in directory /usr/local/apache1/openac-documentatie. Deze directory bevat de volgende onderdelen:

development-working-copy	een lokaal uitgecheckte versie van OpenAC
genereer	een symbolische link naar het script waarmee de documentatie gegenereerd kan worden
html	de html-output na het genereren van de documentatie

Het script gebruikt de volgende onderdelen uit de sandbox map van de OpenAC repository:

Doxyfile	het configuratiebestand van Doxygen
doxypy.py	een doxygen filter voor het verwerken van Python-bestanden
documentatie/custom	custom headers, footers, stylesheets e.d. die gebruikt worden door Doxygen tijdens het genereren van de documentatie

Het script begint met het bijwerken van de lokaal uitgecheckte versie van OpenAC met svn update. Vervolgens wordt de documentatie gegenereerd met Doxygen. Daarna wordt de documentatie naar de uiteindelijke locaties gekopieerd, te weten:

/usr/local/apache1/openac-site/documentatie/html	de documentatie
/usr/local/apache1/openac-site/documentatie/custom	stylesheets e.d.

Genereren documentatie

De online documentatie kan worden gegenereerd met het commando genereer, op de volgende manier:

cd /usr/local/apache1/openac-documentatie
./genereer

genereer is een symbolische link naar het script /usr/local/apache-1/openac-documentatie/svn_checkout/bin/documentatie en verandert dus automatisch als bin/documentatie wordt gewijzigd en gecommit. Na de wijziging is het natuurlijk wel noodzakelijk om een svn update te doen in de map svn_checkout.

Afhankelijkheden

Voor het genereren van de online documentatie moeten de volgende twee pakketten op de server zijn geinstalleerd:

• Graphviz, voor het dynamisch genereren van diagrammen door Doxygen;
• Doxygen, en wel de door ons zelf gewijzigde versie.

Beide pakketten staan in /usr/local/inst, inclusief een myconfig.sh voor de lokale instellingen.