Changes between Initial Version and Version 1 of Documentatie/Ontwikkelaar/Omgeving/Tools

Timestamp:

01/15/12 15:16:04 (14 years ago)

Author:

adriaan

Comment:

--

Documentatie/Ontwikkelaar/Omgeving/Tools

@@ +1 @@
+= Source Control Tools =
+
+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 ==
+
+'''TODO:'''
+Subversion configuratie en best practices.
+
+== Mercurial ==
+
+[http://mercurial.selenic.com/ 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.
+
+=== Installatie ===
+
+Je hebt allereerst Mercurial zelf nodig, en de [http://mercurial.selenic.com/wiki/HgSubversion 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 ~/.hgsubversion
+rm -rf hgsubversion
+   }}}
+
+Maak daarna de configuratie-files aan zoals hieronder omschreven bij [#hg.configuratie Configuratie].
+
+=== Configuratie ===#hg.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 [http://mercurial.selenic.com/wiki/HgSubversion hgsubversion] moet apart worden geinstalleerd.
+
+Subversion-achtige logs krijg je met een ''log template''. Maak een file {{{.hgstyle.svn}}} aan
+met de volgende inhoud; hiermee verwijs je naar een specifieke template file die in dezelfde directory staat.
+   {{{
+changeset = .hgstyle.svn.template
+file = "     {file}\n"
+   }}}
+Maak ook een file {{{.hgstyle.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. 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 {{{.hgignore.python}}}
+met de volgende inhoud:
+   {{{
+syntax: glob
+*.pyc
+*.pyo
+*.py~
+*.py.orig
+*.py.rej
+*.py.bak
+   }}}
+
+Tot slot, moet je in de {{{.hg}}} directory van je clone repository een {{{hgrc}}} zetten die de nodige 
+extensies aanzet en verwijst naar de ignore en templates files. Voeg dit '''toe''' aan de 
+{{{hgrc}}} die er al staat, want er staat al (minstens) een {{{[path]}}} om de pull- en push-bestemming in te stellen.
+   {{{
+[extensions]
+hgext.graphlog =
+mq =
+hgsubversion = ~/.hgsubversion
+rebase =
+
+[ui]
+username = Adriaan de Groot <a.degroot@fenac.nl>
+ignore.python = ~/.hgignore.python
+style = ~/.hgstyle.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 800)
+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.