Maandagochtend staat er een nieuw knopje op een scherm dat vrijdag nog anders was. Voor een gebruiker voelt dat als een verandering die zomaar gebeurt. Achter dat ene knopje zit een traject met een aantal vaste stappen, en dat traject bepaalt niet alleen wanneer iets verandert, maar ook of u er iets van te weten komt en wanneer u een reden hebt om erop te vertrouwen.

Van wijziging naar versienummer

Elke wijziging aan het platform wordt beschreven op het moment dat ze gemaakt wordt: wat er verandert, en van welk soort de wijziging is — een nieuwe functie, een correctie, een aanpassing die niet zichtbaar is voor een gebruiker. Die beschrijving hoort bij de wijziging zelf, niet bij een los document dat achteraf wordt ingevuld: wie de wijziging maakt, schrijft meteen op wat en welk soort, en die twee gegevens samen bepalen automatisch wat er met het versienummer gebeurt. Uit die beschrijvingen wordt het versienummer automatisch afgeleid: een nieuwe functie telt anders mee dan een correctie, en een wijziging die de manier waarop iets werkt fundamenteel verandert, telt weer anders. Er wordt dus niet met de hand beslist "dit wordt versie zoveel" — het volgt uit wat er die periode daadwerkelijk veranderd is. Dat is bewust zo ingericht: een versienummer dat met de hand wordt toegekend, is inconsistent zodra het druk is, en juist dan is een betrouwbaar nummer het nuttigst.

Eerst bèta, dan productie

Een wijziging komt niet rechtstreeks bij u terecht. Ze doorloopt eerst een bèta-omgeving: een omgeving die hetzelfde draait als wat u gebruikt, maar waar nog niemand op vertrouwt voor het eigen werk. Pas als een reeks wijzigingen daar stabiel blijkt, gaat het geheel naar de omgeving die u dagelijks gebruikt. Die tussenstap bestaat om dezelfde reden als een generale repetitie: fouten die pas zichtbaar worden zodra alles samen draait, worden daar gevonden voordat ze bij u belanden. We noemen hier bewust geen namen van de systemen die dat traject uitvoeren — dat is infrastructuur, en de redenering erachter is wat telt, niet de leverancier erachter.

Waarom release notes een eigen stap zijn

Het versienummer dat automatisch wordt afgeleid, is niet hetzelfde als de tekst die u in de app leest onder "wat is er nieuw". Die tekst wordt apart en met de hand geschreven, in gewone taal, voor wie de functie gaat gebruiken in plaats van voor wie de code gaat lezen. Een release notitie doorloopt eerst een conceptstadium voor ze gepubliceerd wordt, zodat er tijd is om de tekst te herlezen voordat ze zichtbaar wordt. Dat is een bewuste keuze: een technische beschrijving van een wijziging en een uitleg die u iets vertelt over uw eigen werk, zijn twee verschillende teksten met een ander publiek, en het is eenvoudiger om ze allebei goed te doen als ze niet dezelfde tekst hoeven te zijn.

De twee sporen — het automatische versienummer en de met de hand geschreven uitleg — lopen daardoor bewust niet helemaal gelijk. Een wijziging die voor de techniek een eigen regel in het versienummer verdient, hoeft voor u als gebruiker geen aparte alinea te krijgen als ze niets aan uw werk verandert; en omgekeerd kan een reeks kleine technische wijzigingen samen één zin in de release notities opleveren, omdat het voor u niet uitmaakt hoeveel afzonderlijke stappen daarachter zaten. De release notities zijn dus een vertaling, geen kopie van de technische geschiedenis.

Hoe u ziet welke versie draait

U hoeft niet te gissen welke versie op dit moment actief is. In het beheerpaneel toont een badge in de bovenbalk het huidige versienummer, en een eigen pagina met release notes geeft de inhoudsopgave van alle versies, met de actief geldende versie gemarkeerd zodat de juiste sectie meteen in beeld komt. Wie wil nagaan of een gemelde correctie al is doorgevoerd, hoeft dus niet te wachten op een antwoord van de klantenservice: de versie staat er, met de bijbehorende uitleg ernaast.

Dat is ook waarom het versienummer en de release notities niet los van elkaar horen te bestaan. Een versienummer zonder uitleg vertelt u dat er iets veranderd is, maar niet wat; een uitleg zonder versienummer vertelt u wat er veranderd is, maar niet sinds wanneer. Samen beantwoorden ze de vraag die bij een nieuw knopje als vanzelf opkomt: is dit nieuw, en zo ja, hoelang al.

Een concreet voorbeeld

Sinds versie 1.2.0 heeft het beheerpaneel een eigen Release notes-pagina, rechtstreeks bereikbaar vanuit elk scherm via een link in de voettekst. De versiebadge in de bovenbalk toont welke versie op dat moment draait, en de inhoudsopgave van de pagina markeert die versie zodat u niet hoeft te zoeken. Dat scherm is de zichtbare kant van het traject dat in dit artikel beschreven staat: de wijzigingen die de afgelopen periode zijn doorgevoerd, herschreven in gewone taal, gekoppeld aan het nummer dat automatisch uit die wijzigingen is afgeleid. Wat u niet ziet, en ook niet hoeft te zien, is de bèta-omgeving waar dezelfde wijzigingen eerst doorheen gingen voordat ze bij u aankwamen.

Wat u nu kunt doen

Wilt u zien hoe release notes er in de praktijk uitzien voor een lopend project? Vraag een demo aan.