| 23 | | == Mercurial == |
| 24 | | |
| 25 | | [http://mercurial.selenic.com/ Mercurial] is een zogeheten ''gedistribueerd'' versiebeheersysteem. Dat betekent |
| 26 | | dat de gehele source en geschiedenis lokaal wordt opgeslagen en lokaal wordt bewerkt. Elke gebruiker heeft |
| 27 | | zijn of haar eigen kopie van de hele geschiedenis, en het is aan de gebruikers om vervolgens hun lokale wijzigingen |
| 28 | | met elkaar te delen. |
| 29 | | |
| 30 | | Het voordeel van zo'n gedistribueerd systeem is dat ontwikkeling -- commits, probeersels, branches en soms ook |
| 31 | | reverts -- losgekoppeld zijn van het publiceren of delen van die stappen. Experimenten kunnen worden uitgevoerd |
| 32 | | zonder een centrale repository te "vervuilen." Daarnaast heeft iedere gebruiker een volledige geschiedenis van |
| 33 | | het project en is het dus mogelijk om grotendeels "offline" te werken -- een voordeel op reis of in de trein. |
| 34 | | |
| 35 | | Mercurial kan heel goed met Subversion repositories overweg als je een plugin installeert. Hierdoor kan je |
| 36 | | een branch van de Subversion repository als Mercurial repository importeren en bewerken, en doet {{{hg push}}} |
| 37 | | hetzelfde als {{{svn commit}}} voor alle nieuwe changesets in je lokale repository. De combinatie van mq en |
| 38 | | hgsubversion maakt het makkelijk om stapsgewijs te ontwikkelen en die geschiedenis te bewaren ook in de |
| 39 | | centrale Subversion repository terwijl je ook makkelijk dingen kunt terugdraaien als het nodig is. |
| 40 | | Je kan ook eigen patches -- bijvoorbeeld extra debugging dingen -- gemakkelijk prive houden terwijl je je |
| 41 | | gewone werk naar de centrale server publiceert. |
| 42 | | |
| 43 | | 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. |
| 44 | | {{{ |
| 45 | | mkdir ~/.hgext |
| 46 | | }}} |
| | 26 | 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). |
| 49 | | === Installatie === |
| 50 | | |
| 51 | | Je hebt allereerst Mercurial zelf nodig, en de [http://mercurial.selenic.com/wiki/HgSubversion hgsubversion] extensie |
| 52 | | moet je apart installeren. Dat gaat het makkelijkst als je Mercurial al hebt. Ga naar je home directory, en |
| 53 | | clone dan de repo: |
| 54 | | {{{ |
| 55 | | hg clone https://bitbucket.org/durin42/hgsubversion |
| 56 | | }}} |
| 57 | | Daarna kan je -- als je de configuratie hieronder ongewijzigd wilt gebruiken -- de map {{{hgsubversion/hgsubversion}}} |
| 58 | | hernoemen naar {{{.hgsubversion}}} en daarna de clone weer weggooien. |
| 59 | | {{{ |
| 60 | | mv hgsubversion/hgsubversion ~/.hgext |
| 61 | | rm -rf hgsubversion |
| 62 | | }}} |
| 63 | | |
| 64 | | Maak daarna de configuratie-files aan zoals hieronder omschreven bij [#hg.configuratie Configuratie]. |
| 65 | | |
| 66 | | === Configuratie ===#hg.configuratie |
| 67 | | |
| 68 | | Er zijn twee extensies ''nodig'' om met Mercurial aan OpenAC te werken (''hgsubversion'' en ''rebase''), en twee ''aanbevolen'' (dat zijn ''graphlog'' en ''mq''). |
| 69 | | Daarnaast is het handig om Mercurial zo te configureren dat je een zinvolle username doorgeeft, |
| 70 | | de artefacten van Python ontwikkeling negeert, en logs produceert die een beetje overeenstemmen |
| 71 | | met Subversion zodat je makkelijk mee kunt praten over "revisie r1". |
| 72 | | |
| 73 | | Vanaf Mercurial v1.7 zijn ''rebase'', ''graphlog'' en ''mq'' allemaal onderdeel van de standaard Mercurial |
| 74 | | configuratie. De extensie [http://mercurial.selenic.com/wiki/HgSubversion hgsubversion] moet apart worden geinstalleerd. |
| 75 | | |
| 76 | | Subversion-achtige logs krijg je met een ''log template''. Maak een file {{{~/.hgext/style.svn}}} aan |
| 77 | | met de volgende inhoud; hiermee verwijs je naar een specifieke template file die in dezelfde directory staat. |
| 78 | | {{{ |
| 79 | | changeset = style.svn.template |
| 80 | | file = " {file}\n" |
| 81 | | }}} |
| 82 | | Maak ook een file {{{~/.hgext/style.svn.template}}} met de template zelf. |
| 83 | | {{{ |
| 84 | | changeset: r{svnrev} {rev}:{node} |
| 85 | | user: {author} |
| 86 | | date: {date|isodate} |
| 87 | | files: {files|stringify|tabindent} |
| 88 | | {desc|fill68|tabindent} |
| 89 | | |
| 90 | | }}} |
| 91 | | Let op spaties in dit template, inclusief de lege regel aan het eind. Hiermee wordt een mengeling van de Subversion en Mercurial logs afgedrukt. |
| 92 | | Bij elke changeset krijg je de Subversion revision te zien (als het bestaat) zoals r1. Daarnaast de Mercurial |
| 93 | | changeset aanduiding met nummer en hash. Alle gewijzigde files worden afgedrukt als ware het de uitvoer van |
| 94 | | {{{svn log -v}}}, en de commit message wordt volledig afgedrukt, uitgelijnd naar 68 kolommen. |
| 95 | | |
| 96 | | Python ontwikkeling zet een boel compiled Python objects in de repository, en ontwikkeling met Mercurial |
| 97 | | kan veel patch artefacten opleveren, met {{{.orig}}} files en backups. Maak een bestand {{{~/.hgext/ignore.python}}} |
| 98 | | met de volgende inhoud: |
| 99 | | {{{ |
| 100 | | syntax: glob |
| 101 | | *.pyc |
| 102 | | *.pyo |
| 103 | | *.py~ |
| 104 | | *.py.orig |
| 105 | | *.py.rej |
| 106 | | *.py.bak |
| 107 | | }}} |
| 108 | | |
| 109 | | 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. |
| 110 | | |
| 111 | | {{{ |
| 112 | | [extensions] |
| 113 | | hgsubversion = ~/.hgext/hgsubversion |
| 114 | | rebase = |
| 115 | | }}} |
| 116 | | |
| 117 | | Maak vervolgens een [#Clone 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. |
| 118 | | Voeg het volgende '''toe''' aan het bestand |
| 119 | | {{{v2.000/.hg/hgrc}}} die er al staat. Er staat al (minstens) een {{{[path]}}} om de pull- en push-bestemming in te stellen. |
| 120 | | {{{ |
| 121 | | [extensions] |
| 122 | | hgext.graphlog = |
| 123 | | mq = |
| 124 | | hgsubversion = ~/.hgext/hgsubversion |
| 125 | | rebase = |
| 126 | | |
| 127 | | [ui] |
| 128 | | username = Adriaan de Groot <iemand@ac-nergenshuizen.nl> |
| 129 | | ignore.python = ~/.hgext/ignore.python |
| 130 | | style = ~/.hgext/style.svn |
| 131 | | }}} |
| 132 | | |
| 133 | | === Clone === |
| 134 | | |
| 135 | | Als Mercurial eenmaal correct is geinstalleerd en geconfigureerd, kan je met |
| 136 | | {{{hg help svn}}} controleren of ''hgsubversion'' wel goed werkt. Daarna kan |
| 137 | | je de OpenAC repository clonen. Merk op dat je maar '''een branch''' tegelijk |
| 138 | | kunt clonen. Dat komt omdat de layout van de Subversion repository van OpenAC |
| 139 | | afwijkt van wat hgsubversion normaal aankan. Een branch is prima, dus je kan |
| 140 | | die releases clonen die je nodig hebt -- voorlopig is dat alleen v2.0: |
| 141 | | {{{ |
| 142 | | hg clone svn+https://svn.openac.fenac.nl/release/v2.000 v2.000 |
| 143 | | }}} |
| 144 | | Dit kan '''lang duren''' terwijl Mercurial elke revisie van die branch (momenteel zo'n 1100) |
| 145 | | ophaalt en vertaalt naar een lokale Mercurial changeset. Als het proces wordt afgebroken, |
| 146 | | dan kan het later hervat worden door in de {{{v2.000}}} directory een {{{hg pull}}} te doen. |
| 147 | | |
| 148 | | === Workflow === |
| 149 | | |
| 150 | | Bij Mercurial zijn veel verschillende workflows mogelijk. Omdat changesets uiteindelijk in |
| 151 | | Subversion terecht moeten komen zijn '''branches en merges niet toegestaan''' op het moment dat je |
| 152 | | naar Subversion pusht. Uiteraard kan je lokale clones maken voor branchy development |
| 153 | | en dan relevante branches met cherry-picking weer in je Subversion clone laten verschijnen |
| 154 | | zonder branches of merges. |
| 155 | | |
| 156 | | Typische workflow ziet er zo uit (met ''mq''): |
| 157 | | |
| 158 | | - Werk de clone bij vanaf de Subversion repository. |
| 159 | | {{{ |
| 160 | | hg pull |
| 161 | | }}} |
| 162 | | - Besluit om aan feature ''X'' te gaan werken, of pak ticket ''N'' aan. Begin een serie |
| 163 | | patches om dat te doen. |
| 164 | | {{{ |
| 165 | | hg qnew -m "Begin feature X" feature-X |
| 166 | | }}} |
| 167 | | - Breng veranderingen aan, besluit dat dit een redelijke stap vooruit is. |
| 168 | | {{{ |
| 169 | | hg qref |
| 170 | | }}} |
| 171 | | - Ondertussen kan je nieuwe commits uit de centrale repository overhalen met {{{hg pull}}}. Die komen |
| 172 | | niet in dezelfde branch als de patches waar je nu mee bezig bent, dus die hebben geen effect tenzij je |
| 173 | | een rebase doet van je patches. Maar je kan wel zien wat er verder gebeurt en ook diffs bekijken of |
| 174 | | eventjes bijwerken om te kijken wat voor effect je veranderingen hebben. |
| 175 | | - Als je een nieuwe patch aan wilt maken, bijvoorbeeld omdat je een afzonderlijke stap in de |
| 176 | | ontwikkeling van je feature wilt zetten of omdat je tussendoor een bug wilt fixen, gebruik je |
| 177 | | {{{hg qnew}}} met een nieuwe patch-naam. |
| 178 | | - Na verloop van tijd denk je "dit kan naar de repository". Dan haal je eventjes al je patches weg, |
| 179 | | werk je helemaal bij vanaf subversion, zet je de patches terug (hier kunnen conflicten optreden, maar |
| 180 | | je hebt de individuele patches om mee te werken en kan met de hand mergen), en push je de |
| 181 | | patches naar de repo. |
| 182 | | {{{ |
| 183 | | hg qpop -a |
| 184 | | hg pull -u |
| 185 | | hg qpush -a |
| 186 | | hg qfin -a |
| 187 | | hg push |
| 188 | | }}} |
| 189 | | - Met de tools van ''mq'' kan je je patches zo ordenen dat je evt. ook zinvolle sub-branches of delen |
| 190 | | van je werk kunt pushen. Hierdoor kan je bijvoorbeeld bug-fixes die je halverwege het ontwikkelen |
| 191 | | doet, naar voren halen in je lokale geschiedenis en dan pushen zonder dat je feature werk beinvloed wordt. |
