TOC(heading=Releases)? TOC(heading=Procedures, sectionindex, compact, depth=3, allactive, Documentatie/Ontwikkelaar/Procedures/)? TOC(heading=Ontwikkelaar, sectionindex, compact, depth=2, allactive, Documentatie/Ontwikkelaar/)? 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 aanmaken

Zie de procedure op deze pagina https://www.fenac.nl/openac/wiki/Documentatie/Ontwikkelaar/Procedures/Starterkit

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/