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.

Starten

• Initiele Clone Maakt een clone in de directory openac-git en gaat vervolgens de (remote) development branch volgen. Bij de eerste clone komt er 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://trac2/home/svn/openac-git
  cd openac-git/
  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

(advanced dingen zoals samenwerken aan een branch in git en later afmaken naar SVN)

Infrastructuur

(dit is de documentatie over hoe de git-svn infrastructuur op de server is geconfigureerd)