= Releases = [[TOC(heading=Inhoudsopgave)]] [[TOC(heading=Onderwerpen, sectionindex, compact, depth=3, Documentatie/Ontwikkelhandleiding/Release/*)]] [[TOC(heading=Hoofdstukken, sectionindex, compact, depth=2, Documentatie/Ontwikkelhandleiding/*)]] OpenAC werkt met '''feature''' based versies. Er is voor elke versie een lijst met tickets (zie de [/roadmap 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. [[Image(release.png)]] 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 [#Pre-Branch stap vooraf aan branchen] gevolgd door het [#Branch branchen zelf], [#Stabilisatie een stabilisatie-fase], [#Test een formele test-fase] en uiteindelijk de melding van een nieuwe [#Release 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 [wiki:/Documentatie/Ontwikkelhandleiding/Source#Wijzigingenovernemen 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 [wiki:/Documentatie/Ontwikkelhandleiding/Source#Clean 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). [[NoteBox(tip, Voorheen (in versie 1) was er een script `bin/release` dat hielp bij het maken van een release door enkele checks uit te voeren en dan stapsgewijs "het nodige" te kopieren, maar in de praktijk bleek dit niet goed te werken.)]] Dingen om in ieder geval te verwijderen uit de nieuwe branch: - `analyse/` bevat scripts die alleen aan de ontwikkelkant interessant zijn - `adaptaties/ac_simpelveld/` en `adaptaties/ac_nederland/` en eventueel andere adaptaties die niet bij een productie-omgeving horen. - `VERSIES.txt` hoeft alleen in development te staan. - `.gitignore` hoeft alleen in development te staan. Nadat je de files hebt verwijderd, markeer de commits waarin je ze verwijdert (in development, `svn merge --record-only -c ../v2.XXX`) zodat je niet per ongeluk merget en daarbij belangrijke files weggooit. Zet ook een tag in de git-repository bij de branch: {{{ ssh trac2 # Als user svn cd openac-git git pull 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 [wiki:Documentatie/Ontwikkelhandleiding/TestProtocol 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 == TODO: procedure met pilot-AC is ergens beschreven? == 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 de adaptatiemap in de nieuwe release schrijfbaar voor centra door 3 regels te kopieren in de TRAC configuratie. Pas `apache/auth/openac-svn.auth` in sysconfig aan. - 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 milstone 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. - '''SVN Bijwerken'''. - Op de FENAC server `openac-svn.auth` aanpassen. Maak een nieuwe section `[/release//adaptaties]` die hetzelfde is als de andere regels met `@centra`. - 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 * OpenAC 2.0 met DOT/Grouper }}} - '''Starterkit'''. Zie [#Starterkit het kopje starterkit], hieronder. Korte versie: {{{ ssh trac2 python bin/starterkit.py -v cp /tmp/random/openac-starterkit- /pad/naar/downloads }}} - '''SVN Configuratie'''. De nieuwe branch moet schrijfbaar worden gemaakt voor de centra (anders kunnen ze niks inleveren). In `sysconfig/apache/auth` staat `openac-svn.auth`. Maak een nieuw kopje aan voor `[/releases/v2.XXX/adaptaties]`. - '''Technische Documentatie'''. Zie [#TechnischeDocumentatie 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= --pass= }}} - '''Announce'''. Stuur aan de OpenAC contactpersonen-mailinglist (`openac@`) een aankondiging van de nieuwe versie. Beste OpenAC contactpersonen, OpenAC versie v is al een aantal weken geleden in pilot genomen door en is nu klaar voor productie. Er zijn een aantal belangrijke verbeteringen .. . De release notes van versie v kunt u vinden op onze projectwebsite: http://www.fenac.nl/openac/wiki/Releases/v Hiermee willen we ook contactpersonen van 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: - [wiki:WikiStart de voorpagina] met een !NoteBox aankondiging van de release. - [wiki:Releases de releases pagina] met de meest recente release - [wiki:Installatiehandleiding/StarterKit starterkit] met nieuwe gegevens - de release-notes pagina van de release zelf = Starterkit = De starterkit wordt gemaakt met NSIS ([http://nsis.sourceforge.net/Main_Page 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. 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. 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. Over het algemeen is dit voldoende: {{{ bin/starterkit.py -v }}} Waarbij VERSIE 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 dan 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 [wiki:Documentatie/Installatiehandleiding/StarterKit starterkit in de installatiehandleiding]. = 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/