Context Navigation

Tools

Timestamp:: 09/09/15 12:11:06 (11 years ago)
Author:: adriaan
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

Documentatie/Ontwikkelaar/Omgeving/Tools

-                      v19
+                      v20
+[[TOC(heading=Documentatie, sectionindex, compact, depth=1, allactive, Documentatie/)]]
+[[TOC(heading=Hoofdstukken, sectionindex, compact, depth=2, allactive, indirect=Documentatie/Ontwikkelhandleiding/TOC)]]
+[[TOC(heading=Onderwerpen, sectionindex, compact, depth=3, allactive, indirect=Documentatie/Ontwikkelhandleiding/Ontwikkelomgeving/TOC)]]
 = Source Control Tools =
-[[TOC(heading=Inhoudsopgave)]]
-[[TOC(heading=Hoofdstukken, sectionindex, compact, depth=2, Documentatie/Ontwikkelhandleiding/*)]]
 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.
+== Repository ==
+De sources van OpenAC staan in een source-repository op https://svn.openac.fenac.nl/ . De source-repository is alleen te benaderen door OpenAC ontwikkelaars en ACs met OpenAC geinstalleerd.
+[[NoteBox(warn, OpenAC is geen Open Source software. Het is alleen beschikbaar voor de Audiologische Centra die zijn aangesloten bij de FENAC.)]]
 == Subversion ==
 …
  - OpenAC v2.010 en later gebruiken allemaal Python 2.7 met Subversion 1.7
+=== !PyCharm ===
+!PyCharm ondersteunt uit zichzelf al verschillende SVN versies; het is voldoende om de starterkit te installeren om een geschikte SVN checkout te krijgen waarmee !PyCharm verder kan. Zie ook de [wiki:IDE#PyCharm PyCharm] handleiding voor OpenAC.
 === SlikSVN ===
 Een geschikte Subversion client voor command-line gebruik is [http://sliksvn.com/ SlikSVN]. Je moet een versie van SlikSVN downloaden die overeenkomt met de Subversion versie van OpenAC die je gebruikt; dat is een 1.5 versie voor oudere OpenAC versies en 1.7 vanaf OpenAC v2.010. Deze zijn te vinden bij de ''older versions'' download link, of [https://sliksvn.com/pub/ hier op de SlikSVN site].
-=== !PyCharm ===
-!PyCharm ondersteunt uit zichzelf al verschillende SVN versies; het is voldoende om de starterkit te installeren om een geschikte SVN checkout te krijgen waarmee !PyCharm verder kan.
 === Linux ===
 …
 == 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.
+Git is een gedistribueerd versiebeheer systeem met een zeer uitgebreide toolset. Git beschikt 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).)]]
 [[NoteBox(warn, Omdat git over ssh gaat, moet je wel naar de OpenAC server kunnen ssh-en. Dat is aan FENAC-ontwikkelaars voorbehouden en gekoppeld aan specifieke IP adressen.)]]
+[[NoteBox(warn, Omdat git over ssh gaat, moet je wel naar de OpenAC server kunnen ssh-en. Dat is aan FENAC-ontwikkelaars voorbehouden en gekoppeld aan specifieke IP adressen. Er is geen openbare OpenAC-git repository.)]]
 === Installatie ===
 …
 }}}
    De laatste van deze drie commando's stelt een mapping in tussen de SVN gebruikersnamen en de git gebruikersgegevens. Zorg ervoor dat jouw gegevens overeenkomen met wat er in de `git-author-file` staat, anders krijg je rare merge conflicten in git.
+ - '''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`).
+=== Eenvoudige 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.
+Deze workflow neemt aan dat je aan '''een''' feature of ticket gaat werken, en daarbij enkele tussentijdse commits doet als een deel van het werk voltooid is. Als het klaar is, gaat het feature of de oplossing voor het ticket in een keer naar de SVN repository; daarbij worden de git commits een-op-een overgezet als SVN commits.
+ - '''Bijwerken''' Werk eerst de OpenAC git checkout bij naar de laatste revisie, en wissel daar naartoe (dit neemt aan dat je geen onvoltooid werk hebt liggen):
    {{{
 git checkout git-svn
 git pull --rebase
+git pull
 }}}
+ - '''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
+ Nu heb je een checkout van een moment. Wijzigingen in OpenAC SVN hebben geen invloed op je checkout tot je opnieuw een ''pull'' doet.
+ - '''Wijzigen''' Je kunt nu gewoon wijzigingen aanbrengen in jouw OpenAC checkout. Dat is niet anders dan met een SVN checkout.
+ - '''Offline''' Git ondersteunt een offline model van werken. Dat betekent dat je git checkout de volledige geschiedenis met zich meedraagt; je kunt offline dus ook `log` of `blame` gebruiken.
+ - '''Log''' Je kan met `git log` de log messages opvragen. Omdat git de geschiedenis ook heeft, heb je daar geen netwerk toegang voor nodig. Er zijn ook grafische tools om de commits te laten zien.
+ - '''Commit''' !PyCharm herkent automatisch een git checkout en je kunt dan inchecken met dezelfde interface als in SVN -- alleen gaat de commit dan naar de lokale git checkout. Je kunt ook met de command-line een commit doen. Gebruik daarbij nog steeds een betekenisvolle commit-message. Een voordeel van git is dat je met ''rebase'' een aantal commits kunt herzien, bijvoorbeeld om de commit-message te verbeteren of om tussentijdse commits samen te voegen.
+ - '''SVN Commit''' Als je tevreden bent met je git commits, kan je met twee stappen de changes overhevelen naar SVN en git weer up-to-date brengen.
    {{{
+git svn rebase
 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.
+ De eerste van deze stappen haalt wijzigingen uit SVN op en probeert jouw wijzigingen er op toe te passen. Als er geen botsingen zijn tussen wat andere ontwikkelaars hebben gedaan en jouw werk, gaat dat goed. Daarna kan je nog een keer testen om te zien dat er geen functionele veranderingen effect hebben op jouw code. Met de tweede stap worden de git commits echt in SVN gezet. Daarna kan je weer verder met de volgende feature.
 === Workflow ===
+=== Branching 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.
+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.
 …
 [[Image(branches.png)]]
 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 [ticket:5150 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 heel soms een remote branch.
+De branch ''git-svn'' komt overeen met SVN zelf. Er zijn twee branches, een genaamd ''backups'' (voor een niet nader gespecificeerd feature) en een genaamd ''ticket5150'' (om [ticket:5150 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 -- misschien was je daar gisteren aan begonnen, en ben je nu met iets anders bezig.
+ - '''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 en verdwijnt die -- de commits worden allemaal omgezet in SVN commits.
+   - '''Maak branch''' Kies een naam voor de lokale branch. Als het voor een ticket is, gebruik dan de naam ''ticketNNNN'' met het ticket nummer erin. Hiermee houd je de ticket-branches duidelijk zichtbaar ten opzichte van feature- en experimenteer-branches. Start de branch op ''git-svn'' zodat je vanaf een bekende SVN revisie begint:
+Om een ticket op te lossen in een aparte '''lokale 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 en verdwijnt die -- de commits worden allemaal omgezet in SVN commits.
+ - '''Maak branch''' Kies een naam voor de lokale branch. Als het voor een ticket is, gebruik dan de naam ''ticketNNNN'' met het ticket nummer erin. Hiermee houd je de ticket-branches duidelijk zichtbaar ten opzichte van feature- en experimenteer-branches. Start de branch op ''git-svn'' zodat je vanaf een bekende SVN revisie begint:
    {{{
 git checkout git-svn
 git checkout -b ticketNNNN
 }}}
    - '''Wissel branch''' Als je tussendoor van branch wilt wisselen -- bijvoorbeeld om verder te werken aan een ander ticket of om ''git-svn'' bij te werken -- dan gebruik je weer `git checkout`, bijvoorbeeld een van deze:
+ - '''Wissel branch''' Als je tussendoor van branch wilt wisselen -- bijvoorbeeld om verder te werken aan een ander ticket of om ''git-svn'' bij te werken -- dan gebruik je weer `git checkout`, bijvoorbeeld een van deze:
    {{{
 git checkout git-svn
 git checkout ticketNNNN
 }}}
    - '''SVN bijwerken''' Zoals gewoonlijk kan je de branch ''git-svn'' bijwerken zoals hierboven beschreven. Maar daarmee heb je niet je eigen wijzigingen overgezet naar (git-)commits vanaf de meest recente SVN revisie. Daarvoor moet je eerst bijwerken vanuit SVN, en dan je eigen commits er bovenop zetten:
+ - '''SVN bijwerken''' Zoals gewoonlijk kan je de branch ''git-svn'' bijwerken zoals hierboven beschreven. Maar daarmee heb je niet je eigen wijzigingen overgezet naar (git-)commits vanaf de meest recente SVN revisie. Daarvoor moet je eerst bijwerken vanuit SVN, en dan je eigen commits er bovenop zetten:
    {{{
 git checkout git-svn
 …
 git rebase git-svn
 }}}
    - '''Geschiedenis aanpassen''' In git doe je heel vaak kleine commits en er kunnen ook "tussentijdse" tussen zitten die op zichzelf niet interessant zijn. Je kunt een branch met commits interactief herschrijven door commits samen te voegen en log-messages te veranderen, voordat je ze naar SVN stuurt. Daarvoor gebruik je de `-i` vlag bij rebase:
+ - '''Geschiedenis aanpassen''' In git doe je heel vaak kleine commits en er kunnen ook "tussentijdse" tussen zitten die op zichzelf niet interessant zijn. Je kunt een branch met commits interactief herschrijven door commits samen te voegen en log-messages te veranderen, voordat je ze naar SVN stuurt. Daarvoor gebruik je de `-i` vlag bij rebase:
    {{{
 git checkout ticketNNNN
 …
 }}}
    Dit start een tekst-editor op met instructies over hoe je de commits kunt her-ordenen of anders aanpassen.
    - '''Branch afmaken''' Ben je helemaal klaar met een branch en wil je de commits in die branch overzetten naar SVN zodat ze ook echt in OpenAC zitten, dan doe je eerst SVN bijwerken, daarna SVN push en tot slot gooi je de branch weg -- in feite gooi je alleen de naam van de branch weg, de commits blijven staan want ze zitten dan al in SVN. Bijwerken en push staan hierboven beschreven. Weggooien van de branch gaat tenslotte zo:
+  - '''Branch afmaken''' Ben je helemaal klaar met een branch en wil je de commits in die branch overzetten naar SVN zodat ze ook echt in OpenAC zitten, dan doe je eerst SVN bijwerken, daarna SVN push en tot slot gooi je de branch weg -- in feite gooi je alleen de naam van de branch weg, de commits blijven staan want ze zitten dan al in SVN. Bijwerken en push staan hierboven beschreven. Weggooien van de branch gaat tenslotte zo:
    {{{
+<alle stapjes van SVN bijwerken>
+git checkout git-svn
+git pull --rebase
+git checkout ticketNNNN
+git rebase git-svn
 git checkout git-svn
 git merge ticketNNNN
 git branch -d ticketNNNN
+git svn dcommit
 }}}
    Bij de `git merge` moet git zoiets zeggen als ''fast forward''. Als je daarentegen een merge-dialoog krijgt, dan is er iets mis en had je eerst SVN moeten bijwerken.
- - '''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 [attachment: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)
+Dit is de documentatie over hoe de git-svn infrastructuur op de server is geconfigureerd; dat gaat volgens de handleiding van tfnico.com, met de volgende details:
+ - In de SVN homedir zijn er twee git repositories, `openac-fetch` en `openac-git`. De fetch-repo is een volledige repo, die '''alleen''' gebruikt wordt om SVN commits om te zetten naar git commits. De repo `openac-git` is een bare repository, waar de SVN commits vervolgens heengaan. Gebruikers clonen `openac-git`. In die repo zitten ook tags voor OpenAC releases e.d., die niet in de fetch-repo zitten. De fetch-repo is eenvoudig automatisch opnieuw te maken door SVN geschiedenis weer te importeren.
+ - Een van de commit hooks draait `bin/openac-gitsvn.sh`, die bij elke commit, de git repositories bijwerkt.
+ - Gebruikers van SVN moeten in de OpenAC repository in `bin/git-author-file` worden toegevoegd '''voordat''' ze hun eerste commit doen, anders stokt de SVN import.