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/)?

Source Control Tools

OpenAC wordt ontwikkeld en onderhouden in een ​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.

Repository

De sources van OpenAC staan in een source-repository op ​https://svn.openac.fenac.nl/ . De source-repository is alleen te benaderen door OpenAC ontwikkelaars en ACs met OpenAC geinstalleerd.

NoteBox(warn, OpenAC is geen Open Source software. Het is alleen beschikbaar voor de Audiologische Centra die zijn aangesloten bij de FENAC.)?

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 ​SlikSVN; onder Linux is het meestal onderdeel van devel-subversion of een dergelijke package.
• IDE. De meeste IDE's hebben geintegreerde SVN ondersteuning. 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 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).

• OpenAC t/m v2.006 gebruikten allemaal Python 2.5 met Subversion 1.5
• OpenAC v2.008 is beschikbaar in twee varianten
• OpenAC v2.010 en later gebruiken allemaal Python 2.7 met Subversion 1.7

Unblocken van een adaptatie

Door een instelling in OpenAC2 kan er voor worden gezorgd dat niet alle adaptaties uit de svn repository geactualiseerd worden. Onderwater is zijn bepaalde adaptatie-directories op svn ignore gezet. Als je de adaptatie directory opent dan zie je dat deze niet de subdirectory codetabellen of sjablonen heeft. Dit wil zelfs op development directory gebeuren.

Dit blokkeren gebeurt wanneer je als een normale medewerker in OpenAC bent inlogt en omdat de systeem beheerder het bijwerken op een bepaalde manier heeft ingesteld.

Om de adaptatie te herstellen, moet je een unblock commando uitvoeren zoals hieronder weergegeven. python .\scripts\svn.py unblock ac_auris of python .\scripts\svn.py unblock all

Denk er aan dat bij het forward porten je in development niet directory's geblokkeerd hebt staan. Hierdoor zal een ingeleverde sjabloon niet in development geimporteerd kunnen worden.

PyCharm

PyCharm ondersteunt uit zichzelf al verschillende SVN versies; het is voldoende om de starterkit te installeren om een geschikte SVN checkout te krijgen waarmee PyCharm verder kan. Zie ook de PyCharm handleiding voor OpenAC.

SlikSVN

Een geschikte Subversion client voor command-line gebruik is ​SlikSVN. Je moet een versie van SlikSVN downloaden die overeenkomt met de Subversion versie van OpenAC die je gebruikt; dat is een 1.5 versie voor oudere OpenAC versies en 1.7 vanaf OpenAC v2.010. Deze zijn te vinden bij de older versions download link, of ​hier op de SlikSVN site.

Linux

Onder Linux is geen starterkit beschikbaar. Meestal zijn zowel subversion als pysvn distro-packages, dus volstaat het om eerst een subversion te installeren, dan OpenAC uit te checken, en dan pysvn te installeren.

Git

Git is een gedistribueerd versiebeheer systeem met een zeer uitgebreide toolset. Git beschikt 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. Er is geen openbare OpenAC-git repository.)?

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 ​nieuwste installer op van ​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.

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.

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.

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.

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.

Eenvoudige 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.

Deze workflow neemt aan dat je aan een feature of ticket gaat werken, en daarbij enkele tussentijdse commits doet als een deel van het werk voltooid is. Als het klaar is, gaat het feature of de oplossing voor het ticket in een keer naar de SVN repository; daarbij worden de git commits een-op-een overgezet als SVN commits.

• Bijwerken Werk eerst de OpenAC git checkout bij naar de laatste revisie, en wissel daar naartoe (dit neemt aan dat je geen onvoltooid werk hebt liggen):

  git checkout git-svn
  git pull
  

  Nu heb je een checkout van een moment. Wijzigingen in OpenAC SVN hebben geen invloed op je checkout tot je opnieuw een pull doet.
• Wijzigen Je kunt nu gewoon wijzigingen aanbrengen in jouw OpenAC checkout. Dat is niet anders dan met een SVN checkout.
• Offline Git ondersteunt een offline model van werken. Dat betekent dat je git checkout de volledige geschiedenis met zich meedraagt; je kunt offline dus ook log of blame gebruiken.
• Log Je kan met git log de log messages opvragen. Omdat git de geschiedenis ook heeft, heb je daar geen netwerk toegang voor nodig. Er zijn ook grafische tools om de commits te laten zien.
• Commit PyCharm herkent automatisch een git checkout en je kunt dan inchecken met dezelfde interface als in SVN -- alleen gaat de commit dan naar de lokale git checkout. Je kunt ook met de command-line een commit doen. Gebruik daarbij nog steeds een betekenisvolle commit-message. Een voordeel van git is dat je met rebase een aantal commits kunt herzien, bijvoorbeeld om de commit-message te verbeteren of om tussentijdse commits samen te voegen.
• SVN Commit Als je tevreden bent met je git commits, kan je met twee stappen de changes overhevelen naar SVN en git weer up-to-date brengen.

  git svn rebase
  git svn dcommit
  

  De eerste van deze stappen haalt wijzigingen uit SVN op en probeert jouw wijzigingen er op toe te passen. Als er geen botsingen zijn tussen wat andere ontwikkelaars hebben gedaan en jouw werk, gaat dat goed. Daarna kan je nog een keer testen om te zien dat er geen functionele veranderingen effect hebben op jouw code. Met de tweede stap worden de git commits echt in SVN gezet. Daarna kan je weer verder met de volgende feature.

Branching Workflow

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.

De branch git-svn komt overeen met SVN zelf. Er zijn twee branches, een genaamd backups (voor een niet nader gespecificeerd feature) en een genaamd ticket5150 (om 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 -- misschien was je daar gisteren aan begonnen, en ben je nu met iets anders bezig.

Om een ticket op te lossen in een aparte lokale 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:

    git checkout git-svn
    git pull --rebase
    git checkout ticketNNNN
    git rebase git-svn
    git checkout git-svn
    git merge ticketNNNN
    git branch -d ticketNNNN
    git svn dcommit
    

    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.

Infrastructuur

Dit is de documentatie over hoe de git-svn infrastructuur op de server is geconfigureerd; dat gaat volgens de handleiding van tfnico.com, met de volgende details:

• In de SVN homedir zijn er twee git repositories, openac-fetch en openac-git. De fetch-repo is een volledige repo, die alleen gebruikt wordt om SVN commits om te zetten naar git commits. De repo openac-git is een bare repository, waar de SVN commits vervolgens heengaan. Gebruikers clonen openac-git. In die repo zitten ook tags voor OpenAC releases e.d., die niet in de fetch-repo zitten. De fetch-repo is eenvoudig automatisch opnieuw te maken door SVN geschiedenis weer te importeren.
• Een van de commit hooks draait bin/openac-gitsvn.sh, die bij elke commit, de git repositories bijwerkt.
• Gebruikers van SVN moeten in de OpenAC repository in bin/git-author-file worden toegevoegd voordat ze hun eerste commit doen, anders stokt de SVN import.