Source Control Tools

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

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.

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/ (uiteindelijk ook v2.nnn/).

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.

Command-Line

TortoiseSVN

OpenAC SVN

Mercurial

​Mercurial is een zogeheten gedistribueerd versiebeheersysteem. Dat betekent dat de gehele source en geschiedenis lokaal wordt opgeslagen en lokaal wordt bewerkt. Elke gebruiker heeft zijn of haar eigen kopie van de hele geschiedenis, en het is aan de gebruikers om vervolgens hun lokale wijzigingen met elkaar te delen.

Het voordeel van zo'n gedistribueerd systeem is dat ontwikkeling -- commits, probeersels, branches en soms ook reverts -- losgekoppeld zijn van het publiceren of delen van die stappen. Experimenten kunnen worden uitgevoerd zonder een centrale repository te "vervuilen." Daarnaast heeft iedere gebruiker een volledige geschiedenis van het project en is het dus mogelijk om grotendeels "offline" te werken -- een voordeel op reis of in de trein.

Mercurial kan heel goed met Subversion repositories overweg als je een plugin installeert. Hierdoor kan je een branch van de Subversion repository als Mercurial repository importeren en bewerken, en doet hg push hetzelfde als svn commit voor alle nieuwe changesets in je lokale repository. De combinatie van mq en hgsubversion maakt het makkelijk om stapsgewijs te ontwikkelen en die geschiedenis te bewaren ook in de centrale Subversion repository terwijl je ook makkelijk dingen kunt terugdraaien als het nodig is. Je kan ook eigen patches -- bijvoorbeeld extra debugging dingen -- gemakkelijk prive houden terwijl je je gewone werk naar de centrale server publiceert.

Maak allereerst een directory om je extra Mercurial configuratie en extensies in te bewaren. Het is het handigst in je home directory, genaamd .hgext. De voorbeelden hieronder gaan allemaal er van uit dat je die directory hebt.

mkdir ~/.hgext

Installatie

Je hebt allereerst Mercurial zelf nodig, en de ​hgsubversion extensie moet je apart installeren. Dat gaat het makkelijkst als je Mercurial al hebt. Ga naar je home directory, en clone dan de repo:

hg clone https://bitbucket.org/durin42/hgsubversion

Daarna kan je -- als je de configuratie hieronder ongewijzigd wilt gebruiken -- de map hgsubversion/hgsubversion hernoemen naar .hgsubversion en daarna de clone weer weggooien.

mv hgsubversion/hgsubversion ~/.hgext
rm -rf hgsubversion

Maak daarna de configuratie-files aan zoals hieronder omschreven bij Configuratie.

Configuratie

Er zijn twee extensies nodig om met Mercurial aan OpenAC te werken (hgsubversion en rebase), en twee aanbevolen (dat zijn graphlog en mq). Daarnaast is het handig om Mercurial zo te configureren dat je een zinvolle username doorgeeft, de artefacten van Python ontwikkeling negeert, en logs produceert die een beetje overeenstemmen met Subversion zodat je makkelijk mee kunt praten over "revisie r1".

Vanaf Mercurial v1.7 zijn rebase, graphlog en mq allemaal onderdeel van de standaard Mercurial configuratie. De extensie ​hgsubversion moet apart worden geinstalleerd.

Subversion-achtige logs krijg je met een log template. Maak een file ~/.hgext/style.svn aan met de volgende inhoud; hiermee verwijs je naar een specifieke template file die in dezelfde directory staat.

changeset = style.svn.template
file = "     {file}\n"

Maak ook een file ~/.hgext/style.svn.template met de template zelf.

changeset:   r{svnrev} {rev}:{node}
user:        {author}
date:        {date|isodate}
files:  {files|stringify|tabindent}
        {desc|fill68|tabindent}

Let op spaties in dit template, inclusief de lege regel aan het eind. Hiermee wordt een mengeling van de Subversion en Mercurial logs afgedrukt. Bij elke changeset krijg je de Subversion revision te zien (als het bestaat) zoals r1. Daarnaast de Mercurial changeset aanduiding met nummer en hash. Alle gewijzigde files worden afgedrukt als ware het de uitvoer van svn log -v, en de commit message wordt volledig afgedrukt, uitgelijnd naar 68 kolommen.

Python ontwikkeling zet een boel compiled Python objects in de repository, en ontwikkeling met Mercurial kan veel patch artefacten opleveren, met .orig files en backups. Maak een bestand ~/.hgext/ignore.python met de volgende inhoud:

syntax: glob
*.pyc
*.pyo
*.py~
*.py.orig
*.py.rej
*.py.bak

Om een checkout te kunnen doen van OpenAC moet je de juiste extensies aanzetten in je ~/.hgrc, door de volgende regels toe te voegen (als er al een section [extensions] is, de twee regels eronder toevoegen.

[extensions]
hgsubversion = ~/.hgext/hgsubversion
rebase =

Maak vervolgens een clone van de repository. Dat levert een directory v2.000/ op en daarbinnen een directory v2.000/.hg waar je de laatste beetjes configuratie kunt neerzetten. Voeg het volgende toe aan het bestand v2.000/.hg/hgrc die er al staat. Er staat al (minstens) een [path] om de pull- en push-bestemming in te stellen.

[extensions]
hgext.graphlog =
mq =
hgsubversion = ~/.hgext/hgsubversion
rebase =

[ui]
username = Adriaan de Groot <iemand@ac-nergenshuizen.nl>
ignore.python = ~/.hgext/ignore.python
style = ~/.hgext/style.svn

Clone

Als Mercurial eenmaal correct is geinstalleerd en geconfigureerd, kan je met hg help svn controleren of hgsubversion wel goed werkt. Daarna kan je de OpenAC repository clonen. Merk op dat je maar een branch tegelijk kunt clonen. Dat komt omdat de layout van de Subversion repository van OpenAC afwijkt van wat hgsubversion normaal aankan. Een branch is prima, dus je kan die releases clonen die je nodig hebt -- voorlopig is dat alleen v2.0:

hg clone svn+https://svn.openac.fenac.nl/release/v2.000 v2.000

Dit kan lang duren terwijl Mercurial elke revisie van die branch (momenteel zo'n 1100) ophaalt en vertaalt naar een lokale Mercurial changeset. Als het proces wordt afgebroken, dan kan het later hervat worden door in de v2.000 directory een hg pull te doen.

Workflow

Bij Mercurial zijn veel verschillende workflows mogelijk. Omdat changesets uiteindelijk in Subversion terecht moeten komen zijn branches en merges niet toegestaan op het moment dat je naar Subversion pusht. Uiteraard kan je lokale clones maken voor branchy development en dan relevante branches met cherry-picking weer in je Subversion clone laten verschijnen zonder branches of merges.

Typische workflow ziet er zo uit (met mq):

• Werk de clone bij vanaf de Subversion repository.

  hg pull
  

• Besluit om aan feature X te gaan werken, of pak ticket N aan. Begin een serie patches om dat te doen.

  hg qnew -m "Begin feature X" feature-X
  

• Breng veranderingen aan, besluit dat dit een redelijke stap vooruit is.

  hg qref
  

• Ondertussen kan je nieuwe commits uit de centrale repository overhalen met hg pull. Die komen niet in dezelfde branch als de patches waar je nu mee bezig bent, dus die hebben geen effect tenzij je een rebase doet van je patches. Maar je kan wel zien wat er verder gebeurt en ook diffs bekijken of eventjes bijwerken om te kijken wat voor effect je veranderingen hebben.
• Als je een nieuwe patch aan wilt maken, bijvoorbeeld omdat je een afzonderlijke stap in de ontwikkeling van je feature wilt zetten of omdat je tussendoor een bug wilt fixen, gebruik je hg qnew met een nieuwe patch-naam.
• Na verloop van tijd denk je "dit kan naar de repository". Dan haal je eventjes al je patches weg, werk je helemaal bij vanaf subversion, zet je de patches terug (hier kunnen conflicten optreden, maar je hebt de individuele patches om mee te werken en kan met de hand mergen), en push je de patches naar de repo.

  hg qpop -a
  hg pull -u
  hg qpush -a
  hg qfin -a
  hg push
  

• Met de tools van mq kan je je patches zo ordenen dat je evt. ook zinvolle sub-branches of delen van je werk kunt pushen. Hierdoor kan je bijvoorbeeld bug-fixes die je halverwege het ontwikkelen doet, naar voren halen in je lokale geschiedenis en dan pushen zonder dat je feature werk beinvloed wordt.

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

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
  

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

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 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 remote branches.

• 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 dcommit en verdwijnt het als lokale branch -- de commits worden allemaal omgezet in SVN commits.
  • Maak branch
  • Wissel branch
  • Branch afmaken Dit is stiekum nog een gepiel. Je wilt je lokale changesets rebasen naar een recente SVN changeset en dan dcommit doen; daarna git-svn en mirror/git-svn bijwerken en de lokale branch (als naam) verwijderen en de commits uit de oude branch die niet meer bereikbaar zijn, garbage collecten. De kunst is om merge-commits te vermijden.

• 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 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)