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.

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.

Wijzigingen die in een release worden ingeleverd, moeten via een SVN merge worden opgenomen in de ontwikkeltak.

Wizigingen overnemen

Het meest gemakkelijke is om wijzigingen naar "voren" over te nemen: van een release versie naar nieuwere release versies, of over naar development. Omdat dit regelmatig moet gebeuren is het het meest gemakkelijk om het automatisch met SVN tools te doen.

svn merge, sinds SVN 1.6, houdt bij welke wijzigingen zijn overgenomen. Daardoor voorkom je dat wijzigingen meer dan een keer overgenomen worden, en het wordt ook vrij makkelijk:

svn pg svn:mergeinfo development
svn merge -r NNN:HEAD release/v1.222 development/
svn commit -m "OVERNEMEN: v1.222 -> development NNN t/m MMM"

Met het eerste commando vraag je de mergeinfo op van SVN. Omdat er sommige oude revisies nooit gemerged zijn op een heldere manier, willen we die ook niet meer overnemen. Kijk wat de laatst-gemergede revisie is (in dit geval gaan we v1.222 naar development mergen, dus zoek de uitvoer regel met release/v1.222 en onthoud de meest recente revisie daar. Zeg dat NNN=r19183, bijvoorbeeld.

Vervolgens doen we de merge zelf. Veranderingen vanaf revisie NNN worden overgenomen van v1.222 naar development. Hierbij kunnen conflicts ontstaan. Los die op.

Tot slot met de commit worden de nieuw gemergede revisies als een enkele commit doorgegeven. Merk vervolgens op dat de svn:mergeinfo veranderd is.

Backports

Het is ook mogelijk om veranderingen over te nemen van nieuwere versies naar oude, de zogenaamde backports. Dit gebeurt als er belangrijke functionaliteit ontwikkeld wordt, zeg in development, dat vervolgens tussen twee releases door uit moet komen, of als er ingewikkelde bugfixes moeten worden overgenomen.

svn merge werkt ook van development naar andere branches, maar in het geval van backports is het vaak handig om specifieke commits over te nemen. Gebruik dan -c NNN in plaats van -r NNN:HEAD om precies een revisie NNN over te nemen. Welke revisies over te nemen kan je lezen uit de timeline van OpenAC of uit svn log.

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

TODO: Geen van ons heeft git echt uitgeprobeerd, maar het heet dat git-subversion bridging eenvoudig is (en ongeveer net zo werkt als bij Mercurial).