TOC(heading=Omgeving, sectionindex, compact, depth=3, allactive, Documentatie/Ontwikkelaar/Omgeving/)? TOC(heading=Procedures, sectionindex, compact, depth=3, allactive, Documentatie/Ontwikkelaar/Procedures/)? TOC(heading=Documentatie, sectionindex, compact, depth=1, allactive, Documentatie/)?

Releases

OpenAC werkt meestal met feature based versies. Er is voor elke versie een lijst met tickets (zie de roadmap) die afgehandeld moeten worden voor die versie. De meeste van die tickets zijn enhancements -- nieuwe dingen voor OpenAC, of aanpassingen aan bestaande functionaliteit -- en slechts enkele zijn defecten die vanwege hun omvang een hele versie sturen.

OpenAC wordt dus steeds uitgebracht (ge-released) als de features van de versie-milestone op de roadmap af zijn.

FENAC ICT stuurt er op aan dat er ongeveer om de drie maanden een release (van een nieuwe versie) is; dat betekent dat de omvang van elke versie (gemeten in aantal tickets) beperkt is, en dat soms tickets gepland worden die pas over een paar versies gerealiseerd zullen worden. Dit wordt zo gedaan zodat we wel tijdig nieuwe versies uit kunnen brengen en geen onrust veroorzaken door sluipende veranderingen in de lopende versie.

(Er zijn versies met releases van bijzondere aard waarbij hier niet aan is vastgehouden, zoals v2.000 en v2.002. Die hebben een erg lange doorlooptijd gehad en hebben meer dan gemiddeld veel enhancements en defecten gehad.)

Het maken van een release omvat vier stappen. In tijd gemeten zou dit drie a vier weken duren, waarbij het niet alle tijd opsoupeert: tijdens het maken van een release kan de ontwikkeling van de volgende versie gewoon doorgaan.

Dit diagram laat zien hoe de ontwikkeling ongeveer gaat. Development is altijd gericht op de volgende versie. Op een gegeven moment zijn alle tickets van een versie-milestone afgehandeld in development en kan er naar een release van die versie toe gewerkt worden. Er zijn vier stappen naar een release:

• Branch. Maak een plek in FENAC source-control om aan de release te werken.
• Stabilize. Zorg er intern voor dat de nieuwe versie stabiel en bruikbaar is.
• Test. Doe praktijk en productie-tests met een of meer pilot-ACs.
• Release. Geef de nieuwe versie vrij voor algemeen gebruik.

De poppetjes in het diagram geven ongeveer aan hoeveel mensen er bij betrokken zijn; de zwarte poppetjes zijn FENAC ICT, andere poppetjes zijn van de (pilot) ACs.

Elke stap wordt hieronder in detail beschreven. Er is een extra, verborgen stap vooraf aan branchen gevolgd door het branchen zelf, een stabilisatie-fase, een formele test-fase en uiteindelijk de melding van een nieuwe release.

Pre-Branch

Voordat het eigenlijke SVN-branchen gebeurt, moet development helemaal up-to-date zijn. Hiervoor werken we de splash-screen bij, zorgen voor het volledig overnemen van adaptatie-wijzigingen en zonodig kern-wijzigingen en doen we een pre-branch test.

• Splash. De splash screen staat in images/splash.png en images/splash.xcf. Van belang is dat het copyright jaar overeenkomt met het jaar van de release.
  • Open images/splash.xcf met GIMP.
  • Klik op de layer achtergrond om die onzichtbaar te maken. Klik dan op het tekst-tool icoon (vette A in de toolbox). Dubbel-klik op het tekstveld dat nog een beetje zichtbaar is, dialoog verschijnt. Pas de tekst aan. De tekst luidt steeds Copyright (C) 2004-nu (waarbij je nu vervangt door het jaar van de release).
  • Sla het XCF-bestand op (File -> Save).
  • Sla nu een export naar PNG op (File -> Save As -> vul splash.png in, filetype wordt automatisch gekozen -> dialoog verschijnt, kies ervoor om de PNG plat te slaan door het vinkje merge visible layers aan te zetten.
  • Controleer met een andere plaatjes-viewer dat de splash nog goed is.
  • Commit de twee gewijzigde bestanden.
• Merge. Neem alle nog-niet-gemergede wijzigingen over van de lopende release (of meerdere releases) naar development. Adaptatie-wijzigingen sowieso, en kern-wijzigingen volgens beleid. Zie hiervoor de alinea wijzigingen overnemen in het source-beheer document.
• Clean. Schoon de code op door de formatterings-tools er op te gebruiken. Dit wordt beschreven in de source-code handleiding onder het kopje clean.
• Test. Draai de unittests (voor de kern) om te controleren dat er geen regressies of onverwachte wijzigingen zijn voorgekomen. Je moet wel een werkernde OpenAC configuratie-directory (bv. .openac) hebben.

  python unittests.py --enable-all --no-adaptaties
  

De unittests horen regelmatig gedraaid te worden en bij gehouden te zijn, maar deze stap vormt een extra controle. Er mogen hier geen overwachte FAIL resultaten bijzitten en al helemaal geen ERRORs (dat vereist onder andere dat je een bruikbaar Grouper test-certificaat hebt geinstalleerd).

Pas als de unittests "clean" zijn (in het ICT werkoverleg kan worden besloten wat dat precies inhoudt) is de pre-branch fase voltooid.

Branch

Het maken van een branch gebeurt door met SVN een kopie te maken van development naar de release/ directory in de SVN repository. Dit gaat het snelst op de SVN server zelf, maar kan ook remote:

SVN=https://svn.openac.fenac.nl/
svn cp $SVN/development/ $SVN/release/v2.XXX

Vervang hierbij v2.XXX door het nummer van de nieuwe versie. Kopieen op deze manier zijn goedkoop: op de server gebruikt het maar heel weinig diskruimte. Als je een specifieke revisie nodig hebt (bijvoorbeeld omdat er recent wijzigingen in development/ zijn gemaakt die je niet mee wilt nemen in de branch) kan je development/@rNNN gebruiken.

Daarna kan je (als ontwikkelaar) meteen de nieuwe branch uitchecken en eventueel opschoningsacties (ongeschikte adaptaties of hulp-directories verwijderen).

SVN=https://svn.openac.fenac.nl/
svn co $SVN/release/v2.XXX

Dingen om in ieder geval te verwijderen uit de nieuwe branch:

• scripts en adaptaties die alleen aan de ontwikkelkant interessant zijn.
• bestanden die alleen in development hoeven te staan.
• migratiescripts van eerdere versies.

Op dit moment ziet dat er zo uit (aannemend dat je de checkout al hebt gemaakt). Vergeet niet de wijziging te committen in deze nieuwe versie.

cd v2.XXX
svn rm analyse adaptaties/ac_nederland
svn rm VERSIES.txt .gitignore
  # Herhaal voor alle eerdere migraties
svn rm scripts/migraties/v2.006.py

Nadat je de files hebt verwijderd, markeer de commits waarin je ze verwijdert (in development, svn merge --record-only -c <rev> ../v2.XXX) zodat je niet per ongeluk merget en daarbij belangrijke files weggooit.

cd ../development
svn up
svn merge --record-only -c PREV ../v2.XXX

Zet ook een tag in de git-repository bij de branch:

ssh trac2  # Als user svn
cd openac-git
git log -1  # Check dat het up-to-date is
git tag branch-v2.XXX HEAD

Stabilisatie

In de stabilisatie-fase gaan we op zoek naar bugs die zich in de kersverse release voordoen voordat dit zichtbaar wordt voor de ACs. Problemen die hier gevonden en opgelost worden, kunnen ook zo opgelost worden in development.

• Test. Draai de unittests nog een keer om te controleren of de release nu als aparte versie nog werkt. Draai vervolgens ook de adaptatie-unittests:

  python unittests.py --enable-all --no-adaptaties
  python unittests.py --with-adaptaties
  

  De gewone unittests gebruiken de geconfigureerde OpenAC adaptatie, terwijl de adaptatie-unittests voor elk van de adaptaties een login simuleert en vervolgens op alle knoppen "drukt". De unit test maakt gebruik van lege, standalone sqlite3-databases.
• Systeemtest. De systeemtest vormt een automatische back-to-back test voor de academische huizen. Deze voeren we bij elke release uit. In overleg met academische huizen wordt het testrapport overlegd, maar meestal blijft dit intern. TODO: hoe draai je de systeemtest?
• Testprotocol. Loop het testprotocol door. Dit is een handmatige test van functionaliteit door eindgebruikers. Het testprotocol wordt af-en-toe uitgebreid met nieuwe specifieke situaties om uit te proberen. Het is nuttig om het protocol uit te printen en vervolgens stappen af te strepen.

Als de nieuwe versie na enig serieus getest stabiel lijkt, is de stabilisatiefase voorbij (mits de unittests nog met succes doorlopen worden). Let hierbij op dat er wel een volledige ketentest van gebruikershandelingen uitgevoerd wordt.

Tijdens de stabilisatiefase (evt. al pre-branch) kunnen de release-notes van de nieuwe versie geschreven worden. Gebruik hiervoor een van de bestaande release-notes pagina's als sjabloon, verwijder de specifieke tekst en begin de notes op te stellen aan de hand van de log van wijzigingen.

Als je een git clone hebt, kan je vanaf de vorige release een log opvragen vanaf de tag: git log --reverse branch-v2.008..HEAD (in dit geval vanaf v2.008, in voorbereiding op v2.010).

Test

NoteBox(tip, TODO: procedure met pilot-AC is ergens beschreven?)?

Aan het begin van de testperiode wordt het testen aangekondigd:

• Stuur een mailtje met aankondiging van de tests naar het werkverband, naar de taakgroep ICT en naar de managers.

Beste OpenAC contactpersonen,

OpenAC versie v<nummer> is klaar om getest te worden. Voor deze release leidt <pilot-AC> als pilot-AC. Andere AC's wordt aangeraden deze test-versie over een week in gebruik te nemen voor test als de eerste bevindingen verwerkt zijn.

• Stuur het pilot-AC alvast instructies om te schakelen naar de branch, en misschien ook een eerste starterkit / installer.

Release

De technische handelingen voor het uitbrengen van een release hebben te maken met SVN en TRAC. Daarnaast wordt meestal een nieuwe starterkit en technische documentatie gemaakt, en tot slot wordt de release van de nieuwe versie aangekondigd aan de ACs.

• TRAC Bijwerken.
  • Maak in TRAC via de Admin panel een nieuwe versie aan in admin/ticket/versions zodat die voortaan te selecteren is in de web-interface. Zet geen "v" in deze versienummers.
  • Maak een nieuwe milestone aan voor een nieuw en toekomstig te plannen release. Meestal hebben we nu drie releases vooruit milestones.
  • Maak ook in het voren alvast een release-notes pagina aan voor een volgende release. Als versie N ge-released wordt, maak dan een release-notes pagina aan voor N+1 (om ontwikkelingen in te noteren) en milestones voor N+1 en N+2 (voor de planning).
• SVN Bijwerken.
  • VERSIES.txt bijwerken in development. Voeg een nieuwe regel toe bovenaan VERSIES.txt om de nieuwe versie zichtbaar te maken in het versiebeheerscherm van OpenAC. We houden tegenwoordig de release-notes op TRAC bij, dus er hoeft geen lang verhaal in te staan. Een regel met de versie en een regel samenvatting is genoeg. Let op de twee lege regels! Zodra dit is gecommit is de nieuwe versie zichtbaar in OpenAC en krijgen de centra een waarschuwing dat ze niet de nieuwste versie gebruiken, dus doe deze stap pas als je weet dat de vervolgstappen snel komen.

    v2.002, 22-10-2012
    <leeg>
    * OpenAC 2.0 met DOT/Grouper
    <leeg>
    

• Starterkit. Zie het kopje starterkit, hieronder.
• SVN Configuratie. De nieuwe branch moet schrijfbaar worden gemaakt voor de centra (anders kunnen ze niks inleveren). Op de FENAC server apache/auth/openac-svn.auth in sysconfig aanpassen. Maak een nieuwe section [/release/<versie>/adaptaties] die hetzelfde is als de andere regels met @centra. Daarna make install-auth-openac.
• Technische Documentatie. Zie het kopje technische documentatie, hieronder. Korte versie:

  ssh trac2
  svn up ~/src/development
  cd ~/src/development
  export CHECKOUT_ROOT=~/src
  export DOCUMENTATION_DEST=/pad/naar/downloads/documentatie
  sh bin/documentatie.sh
  python bin/documentatie-intern.py --update --user=<user> --pass=<pass>
  

• Announce. Stuur aan de OpenAC contactpersonen-mailinglist (openac@) en aan het werkverband en aan de managers een aankondiging van de nieuwe versie.

Beste OpenAC contactpersonen,

OpenAC versie v<nummer> is al een aantal weken geleden in pilot genomen door <pilot-AC> en is nu klaar voor productie. Er zijn een aantal belangrijke verbeteringen .. <maximaal twee of drie zinnen over nieuwe dingen>. De release notes van versie v<nummer> kunt u vinden op onze projectwebsite:

​http://www.fenac.nl/openac/wiki/Releases/v<nummer>

Hiermee willen we ook contactpersonen van <pilot-AC> bedanken voor hun samenwerking en waardevolle feedback in de testperiode van deze release.

• Website. Werk de volgende pagina's bij met gegevens over de nieuwe release:
  • de voorpagina met een NoteBox aankondiging van de release.
  • de releases pagina met de meest recente release
  • starterkit met nieuwe gegevens
  • de release-notes pagina van de release zelf

Starterkit

De starterkit wordt gemaakt met NSIS (​NullSoft Scriptable Installation System). NSIS heeft een beperkt script-taaltje; daarmee kan je een paar configuratie-vragen stellen en vervolgens OpenAC met een specifieke configuratie op een bepaalde plek installeren.

Vanaf OpenAC v2.016 kan er ook met ​WiX toolset een MSI installer gemaakt. Deze installer integreert volledig met het Windows Add/Remove Programs concept en is wellicht makkelijker te integreren in automatische roll-outs.

Algemeen

De starterkit wordt gemaakt door het script bin/starterkit.py. Gebruik --help voor configuratie-opties bij het maken van de starterkit. Gebruik -v om een OpenAC versie op te geven en -r voor een specifieke revisie. Als je geen -r doet, dan doet hij de nieuwste revisie van dat moment.

De versie die je bij -v opgeeft, is de naam van een inmiddels aangemaakte release/ branch is. De "v" in een versie-nummer is optioneel, dus -v 2.002 is hetzelfde als -v v2.002. Er wordt een checkout gemaakt van die versie, samen met de Python runtime, dan wordt van de template NSIS-file een specifiek installer-script gemaakt en met makensis tot een starterkit.exe gemaakt. Op de OpenAC server duurt dit ongeveer 20 minuten in totaal.

De resulterende executable mag naar de downloads folder worden gekopieerd. Er worden MD5 en SHA1 checksums geprint voor gebruik in de release notes en op de pagina over de starterkit in de beheershandleiding.

Verdere command-line opties voor starterkit.py zijn:

• --debug om debug-logging aan te zetten en de sessie-log weg te schrijven naar sessie.log in de huidige directory.
• --skip-nsis om geen NSIS (installer-executable) te maken ook al zou dat kunnen.
• --skip-wix om geen WiX (MSI installer) te maken ook al zou dat kunnen.
• --skip-checkout om geen nieuwe checkout te doen; dit is alleen handig in combinatie met --workdir, en dan vooral als je de tools aan het aanpassen bent zodat je niet steeds ook op het netwerk en de checkout hoeft te wachten.
• --workdir (of -d) om aan te geven waar gewerkt moet worden in plaats van in een tijdelijke directory. Geef een pad op dat al bestaat; checkouts worden in de workdir gedaan.

NSIS

Op de OpenAC server is makensis geinstalleerd. Soms zijn er Linux packages voor; op SourceForge is in ieder geval een setup.exe beschikbaar voor Windows. Installeer NSIS en zorg dat je vanuit de shell makensis aan kunt roepen. Om een starterkit te maken heb je verder een checkout van development nodig (of in ieder geval development/bin), makensis en een shell.

Op dit moment is de procedure op de NSIS starterkit te bouwen op de FENAC server:

stap 1. Inloggen via root op fenac.nl

stap 2. Kijk of de directory /home/<usernaam> bestaat zo niet maak deze als root aan.

Geef deze directory recursief de ownership <usernaam> group fenac of users. Dit kan via mc => file. In deze directory gaan we de checkout doen van de setup-build tools

stap 3. su naar bob (Men heeft bewust gekozen om normale track users geen bash omgeving te geven. Dit is geloof ik via ssh config ingesteld)

stap 4. Doe een df. Kijk of er 2200 Mb beschikbaar is, zo niet

• Kijk of je /home/adriaan/<versie> kunt deleten of die van een andere user.
• Kijk of je logfiles kunt deleten. Een versie sourcetree is 990Mb in Windows anno 02-02-2018.

stap 5. Ga nu de bin/starterkit build omgeving binnen halen (z.g.n. bin checkout doen)

Voer het volgende in je bash/ssh

SVN=https://svn.openac.fenac.nl/
svn co $SVN/development/bin  
python bin/starterkit.py -v 2.XXX

stap 6. Start de build van een setup

python bin/starterkit.py -v 2.XXX

Na verloop van tijd krijg je wat output, die vertelt waar de resulterende starterkit-executable staat. Er wordt ook een standaard release-blurb getoond die je naar de starterkit-pagina kunt kopieren.

  # Pad van gegenereerde starterkit overnemen
cp /tmp/tmpXXX/openac-v2.XXX-starterkit.exe /srv/www/openac.fenac.nl/openac/downloads/

WiX

De WiX toolset draait onder Windows. Installeer het vanaf de WiX toolset pagina. Versie 3.11 is de courante versie en het starterkit-script verwacht dat het geinstalleerd is en in het pad van de command-prompt te vinden is.

De WiX tools werken vanaf een of meer XML bestanden (.wxs) als een compiler chain: .wxs wordt eerst gecompileerd naar een object-file (.wixobj) en dan worden een of meer object-files samengevoegd tot een MSI installer.

De toolset raadt zelf aan om de XML bestanden met de hand te schrijven. Een deel daarvan is nodig, maar voor zoiets als de Python runtime is het ondoenlijk. Er zijn ook tools om uit een geinstalleerde mappen-structuur een .wxs te genereren. Het diagram laat zien hoe het (schematisch) werkt.

Het starterkit.py script gebruikt heat.exe om voor de OpenAC sources en voor de Python runtime een .wxs te maken, en compileert die; ook de handgeschreven starterkit.wxs wordt gecompileerd, en het geheel samengevoegd tot een installer.

Er staat versie-informatie in starterkit.wxs. In het bijzonder is het absoluut noodzakelijk om een nieuwe upgrade-code (regel 5) te maken als je een nieuwe installer maakt (niet vergeten om die nieuwe UUID te committen!) omdat je anders geen upgrade pad hebt en je eerst OpenAC moet deinstalleren voordat je de MSI kunt installeren.

Het uitgeven van nieuwe MSI installers is dus een zwaardere, en duurdere, operatie dan de starterkit executable.

Technische Documentatie

In een checkout van development/ heb je bin/documentatie.sh. Die kan je draaien op de server (of elders waar je een shell en Doxygen 1.5 of later hebt). Pas het script eerst aan zodat je DOCUMENTATION_DEST en CHECKOUT_ROOT goed hebt staan (de plek waar de documentatie terecht moet komen en de plek waar development/ staat).

Het script maakt vanuit development/ een nieuwe versie van de documentatie. Bestanden uit bin/documentatie/custom/ worden gebruikt voor de versiering van de documentatie.

De documentatie verschijnt vervolgens onder https://www.fenac.nl/openac/downloads/documentatie/