= Source Control Tools =

[[TOC(heading=Inhoudsopgave)]]
[[TOC(heading=Hoofdstukken, sectionindex, compact, depth=2, Documentatie/Ontwikkelhandleiding/*)]]

OpenAC wordt ontwikkeld en onderhouden in een [http://subversion.apache.org/ Subversion] repository.
Subversion is de standaard manier om met die repository om te gaan, maar het is ook mogelijk om
met andere versiebeheer programma's aan OpenAC te werken.

== Subversion ==

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/}}} of {{{v2.nnn/}}}. De huidige versie van OpenAC is versie 2, dus de `v2.nnn` directories zijn actueel.

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. 

FENAC ICT ondersteunt de twee meest recente versies van OpenAC. Na een release wordt de voor-vorige versie niet meer ondersteund (met een zekere overgangsperiode, maar na de release van v2.010 is v2.008 nog ondersteund, v2.007 niet lang meer en v2.006 helemaal niet).

Om te werken met Subversion heb je een Subversion '''client''' nodig, die
communiceert met de repository op de FENAC server. Er zijn verschillende clients beschikbaar:

 - Command-line. Dit is de meest traditionele manier om met SVN te werken. De command-line client kan je onder Windows installeren via [https://sliksvn.com/download/ SlikSVN]; onder Linux is het meestal onderdeel van devel-subversion of een dergelijke package.
 - IDE. De meeste IDE's hebben geintegreerde SVN ondersteuning. [wiki:Documentatie/Ontwikkelhandleiding/Ontwikkelomgeving#PyCharm PyCharm] kan eenvoudig worden geconfigureerd met een SVN checkout van OpenAC.
 - OpenAC. Dit maakt gebruik van de SVN ondersteuning in OpenAC zelf. Het versiebeheerscherm maakt hier gebruik van. Je moet wel een werkende OpenAC-installatie hebben. Het [wiki:Documentatie/Beheershandleiding/Scripts#SVNClient OpenAC-script ''svn''] kan een aantal handelingen uitvoeren (update, switch, fix), maar lang niet alles (zoals committen).


Merk op dat SVN een aantal verschillende versies heeft (gehad). De versie van SVN die je gebruikt voor het bewerken van de sources van OpenAC moet overeenkomen met de versie van SVN die in OpenAC ingebakken zit -- zo niet, dan kan OpenAC misschien niet via versiebeheer de zichzelf bijwerken. Dat merk je aan de rode melding bij het opstarten ''deze OpenAC-versie heeft geen versiebeheerondersteuning.'' (Dat kan ook als je geen SVN gebruikt voor de checkout).



== Git ==

Git is een gedistribueerd versiebeheer systeem met een zeer uitgebreide toolset en een nogal cryptische ''core'' -- een kern waarmee je wel alles kunt. Git beschikt ook over een goeie SVN bridge, zodat je met git kunt werken en  de gedistribueerde kenmerken van git kunt gebruiken en '''tegelijk''' ook gecontroleerd met Subversion om kunt gaan. Hierdoor wordt het mogelijk om samen te werken in git en dan af te ronden in Subversion.


[[NoteBox(tip, Hier staat alleen hoe je OpenAC-specifieke handelingen voor git moet ondernemen. Een [http://git-scm.com/book/en/Git-Basics algemene handleiding voor git] is het boek Pro Git (gratis via de git site).)]]

[[NoteBox(warn, Omdat git over ssh gaat, moet je wel naar de OpenAC server kunnen ssh-en. Dat is aan FENAC-ontwikkelaars voorbehouden en gekoppeld aan specifieke IP adressen.)]]

=== Installatie ===

Onder Linux is git een van de standaard ontwikkeltools die bij je distro zitten. Installatie wisselt per distro, maar de package zal waarschijnlijk ''git'' heten (in OpenSUSE, `zypper in git`).

Onder Windows, haal de [http://git-scm.com/download/win nieuwste installer] op van [http://git-scm.com/ git-scm.com]. Ga de installer uitvoeren. Tijdens het installeren kan je kiezen welke componenten geinstallerd worden. De defaults zijn goed. Ik zet zelf het vinkje bij ''Use a !TrueType font'' omdat ik dat prettiger vind lezen in een console window.

[[Image(git-win1.PNG,class=inline)]]

Een volgende keuze die je moet maken is of je git en andere meegeleverde tools bij '''alle''' command-prompt windows wilt hebben, of alleen in speciale ''Git Bash'' windows. Dat hangt af van hoe veel je de command-prompt normaal gebruikt en war je gewoontes zijn. Ik kies voor de optie om git overal beschikbaar te maken, omdat ik graag de UNIX-style tools heb. Maar de default keuze, alleen ''Git Bash'', is ook prima.

[[Image(git-win2.PNG,class=inline)]]

Vervolgens moet je kiezen hoe git met line-endings omgaat. Kies hier voor ''checkout Windows, commit UNIX''. Dit komt overeen met de SVN instelling `eol-style:LF` zodat alleen LF in de repository komt, terwijl de files makkelijk(er) te editen zijn met iets als Wordpad.

[[Image(git-win3.PNG, class=inline)]]

[[Image(git-win4.PNG, class=inline-right)]]Hierna wordt git geinstalleerd op het systeem en krijg je een bureau-blad icoontje. Als je dit opstart, krijg je een Linux-achtige shell omgeving waarin je git uit kunt voeren. De commando's hieronder gaan er allemaal van uit dat je zo'n git bash window tot je beschikking hebt.

[[Image(git-win5.PNG, class=inline)]]

=== Starten ===

 - '''SSH''' Maak eerst een SSH-key aan waarmee je naar de FENAC server kunt SSH'en. Hiervoor is een gebruikers-login op de server zelf nodig. Je kan alleen vanaf Audcom bij die server. Configureer SSH vervolgens zo dat je een nette alias (zeg ''openac'') voor die verbinding. Dat kan door in je `~/.ssh/config` dit op te nemen:
   {{{
Host openac
        HostName svn.openac.fenac.nl
        User mijzelf
        IdentityFile ~/.ssh/id_openac
}}}
 - '''Initiele Clone''' Dit maakt een clone in de directory `openac-git` en gaat vervolgens
   de (remote) development branch volgen. Bij de eerste clone komt er misschien een foutmelding
   dat er geen checkout gemaakt kan worden omdat HEAD geen remote-ref heeft. Die kan
   je negeren, want je wilt toch een andere branch volgen.
   {{{
git clone -o mirror ssh://openac/home/svn/openac-git
cd openac-git/
git checkout -t mirror/git-svn
git svn init --prefix=mirror/ https://svn.openac.fenac.nl/development
git svn dcommit
}}}
 - '''Configuratie''' Voordat je verder werkt met de repository, kan je het beste je gebruikersgegevens zoals die in de log worden vertoond, aanpassen (anders klaagt `git commit` erover). Hiermee stel je (voor '''deze''' repository alleen) je te-vertonen gebruikersnaam en email adres in. Traditioneel gebruiken we alleen een voornaam:
   {{{
git config user.name "Adriaan"
git config user.email "a.degroot@fenac.nl"
git config svn.authorsfile bin/git-author-file
}}}
   De laatste van deze drie commando's stelt een mapping in tussen de SVN gebruikersnamen en de git gebruikersgegevens. Zorg ervoor dat jouw gegevens overeenkomen met wat er in de `git-author-file` staat, anders krijg je rare merge conflicten in git.
 - '''Update''' Dit werkt de checked out working-directory bij naar de
   huidige stand van SVN, met behoud van eigen commits sinds de laatste keer
   (zoals `svn up`).
   {{{
git checkout git-svn
git pull --rebase
}}}
 - '''Commit''' In git kan je altijd lokaal committen. Deze commits gaan niet (direct) naar de centrale server, en je kan dus experimenteren en/of een feature in meerdere commits opbouwen zonder dat dat zichtbaar is voor de buitenwereld. Hoe git commits te doen staat in de git handleidingen.
 - '''SVN Push''' Als je iets af hebt en dat om wilt zetten naar SVN changesets, doe je
   {{{
git svn dcommit
}}}
   Hiermee worden je git commits een-voor-een naar SVN gestuurd als SVN commits. Je checkout wordt ook (net als bij update) bijgewerkt naar de meest recente SVN checkout.

=== Workflow ===

Op de manier zoals hierboven is omschreven kan je git gebruiken als SVN client. Enig voordeel ten opzichte van SVN zelf is dat je ook lokale commits kunt doen en iets lokaal af kunt maken zonder dat je tussentijdse commits naar SVN hoeft te doen. Aan het eind van de rit kan je met ''dcommit'' je changesets naar SVN pushen. Eventueel kan je ook met '''branches''' werken om changesets onafhankelijk van elkaar te ontwikkelen, of om verschillende problemen los van elkaar op te lossen.

Het plaatje hieronder laat een (eenvoudige) grafische weergave zien van branches in git tijdens OpenAC ontwikkeling.

[[Image(branches.png)]]

De branch ''git-svn'' komt overeen met SVN zelf. Er zijn twee remote branches, een genaamd ''backups'' (voor een niet nader gespecificeerd feature) en een genaamd ''ticket5150'' (om [ticket:5150 dat ticket] op te lossen). De ticket-branch is net geopend en loopt vanaf de nieuwste SVN revisie verder. De backups-branch is een stuk ouder. Onder normale omstandigheden zouden er meer branches zijn van wisselende ouderdom, en ook een mengsel van lokale en heel soms een remote branch.


 - '''Lokale branch''' Om een ticket op te lossen in een aparte (lokale, heel goedkope) branch, maak je een branch, schakel je daar op over, werk je normaal en doe je gewoon git commits. Af-en-toe controleer je dat je hele geschiedenis van fixes nog werkt ten opzichte van wat er nu in SVN staat. Je kan tussendoor ook wisselen naar andere branches of naar de huidige staat van SVN als je aan iets anders moet werken. Tenslotte maak je de branch af met en verdwijnt die -- de commits worden allemaal omgezet in SVN commits.
   - '''Maak branch''' Kies een naam voor de lokale branch. Als het voor een ticket is, gebruik dan de naam ''ticketNNNN'' met het ticket nummer erin. Hiermee houd je de ticket-branches duidelijk zichtbaar ten opzichte van feature- en experimenteer-branches. Start de branch op ''git-svn'' zodat je vanaf een bekende SVN revisie begint:
   {{{
git checkout git-svn
git checkout -b ticketNNNN
}}}
   - '''Wissel branch''' Als je tussendoor van branch wilt wisselen -- bijvoorbeeld om verder te werken aan een ander ticket of om ''git-svn'' bij te werken -- dan gebruik je weer `git checkout`, bijvoorbeeld een van deze:
   {{{
git checkout git-svn
git checkout ticketNNNN
}}}
   - '''SVN bijwerken''' Zoals gewoonlijk kan je de branch ''git-svn'' bijwerken zoals hierboven beschreven. Maar daarmee heb je niet je eigen wijzigingen overgezet naar (git-)commits vanaf de meest recente SVN revisie. Daarvoor moet je eerst bijwerken vanuit SVN, en dan je eigen commits er bovenop zetten:
   {{{
git checkout git-svn
git pull --rebase
git checkout ticketNNNN
git rebase git-svn
}}}
   - '''Geschiedenis aanpassen''' In git doe je heel vaak kleine commits en er kunnen ook "tussentijdse" tussen zitten die op zichzelf niet interessant zijn. Je kunt een branch met commits interactief herschrijven door commits samen te voegen en log-messages te veranderen, voordat je ze naar SVN stuurt. Daarvoor gebruik je de `-i` vlag bij rebase:
   {{{
git checkout ticketNNNN
git rebase -i git-svn
}}}
   Dit start een tekst-editor op met instructies over hoe je de commits kunt her-ordenen of anders aanpassen.
   - '''Branch afmaken''' Ben je helemaal klaar met een branch en wil je de commits in die branch overzetten naar SVN zodat ze ook echt in OpenAC zitten, dan doe je eerst SVN bijwerken, daarna SVN push en tot slot gooi je de branch weg -- in feite gooi je alleen de naam van de branch weg, de commits blijven staan want ze zitten dan al in SVN. Bijwerken en push staan hierboven beschreven. Weggooien van de branch gaat tenslotte zo:
   {{{
<alle stapjes van SVN bijwerken>
git checkout git-svn
git merge ticketNNNN
git branch -d ticketNNNN
}}}
   Bij de `git merge` moet git zoiets zeggen als ''fast forward''. Als je daarentegen een merge-dialoog krijgt, dan is er iets mis en had je eerst SVN moeten bijwerken.
 - '''Remote branch''' Als je wilt samenwerken aan een feature, maar niet wilt dat dit meteen zichtbaar is in SVN, of als je een bugfix hebt maar die wilt laten reviewer, dan kan je een lokale branch als '''remote''' branch in de git repository pushen. Dan wordt de branch zichtbaar voor anderen die de git repository gebruiken, maar wordt het niet naar SVN gepusht. Hierdoor kan er "onzichtbaar" aan iets gewerkt worden totdat het af is, en kan iets goed getest worden voordat het in SVN komt.
   - '''Branch publiceren'''
   - '''Branches volgen'''
   - '''Branch afmaken''' Als je een remote branch hebt (voor een bepaald ticket, zeg) en je weet dat die klaar is (iedereen heeft het gezien, changesets gepushed, is getest enzovoorst) dan kan je het afmaken door de branch naar SVN te pushen. Ondertussen kan je geschiedenis herschrijven. Daarna moet je wat opruimwerk doen. In [attachment:git-svn-finish.sh] staat een script ter illustratie (waarschijnlijk kan dat makkelijker).

=== Infrastructuur ===

(dit is de documentatie over hoe de git-svn infrastructuur op de server is geconfigureerd; dat gaat allemaal volgens de handleiding van tfnico.com)