Werken met Github

Al enige tijd werk ik met Github, een site waar je
als open source ontwikkelaar, gratis, je projecten kunt hosten.

Ik heb daar in de loop der jaren al wat projecten op gezet die,
natuurlijk, door iedereen vrij te gebruiken zijn.

Sinds enige tijd ben ik ook een van de, hobbymatige, ontwikkelaars van
het Ansible configuratie tool en ik heb ook al een
aantal patches ingediend.

Maar bij het indienen van die patches ontstaat vaak een probleem.
Aangezien git het beleid heeft om vaak te committen (en ik dat ook
trouw doe), blijkt het erg onhandig om dit soort patches op een goede
manier in te dienen. Het verzoek van de beheerder van de hoofdtak zal
dan ook zeker zijn on squashed commits, het tot een commit
samengevoegde commits, in te dienen. Dit gaat goed, totdat er een
aanpassing gemaakt moet worden aan de al ingediende patch. Er blijken dan
altijd conflicten te ontstaan, die weer lastig op te lossen zijn.

Na een tijd zoeken en proberen heb ik de volgende werkwijze ontwikkeld,
die goed werkt:

• Als je het nog niet hebt, maak dan een account aan op github

• Zorg dat git goed geconfigureerd is:

  git config --global user.name 'Ton Kersten'
  git config --global user.email 'Ton.Kersten@ATComputing.nl'
  

• Kopieer het gewenste project op github naar je eigen account, oftwel
  "Maak een vork"

• Kloon deze vork naar je eigen PC om zelf wijzigingen aan te brengen

  git clone https://github.com/tonk/ansible
  

• In de meeste gevallen is het wel aan te raden om eerst een nieuwe tak
  te starten, omdat je in github slechts 1 patch-aanvraag per tak
  mag hebben.

  git checkout -b nieuwetak
  

• Nu kun je allerlei aanpassingen maken, committen, testen en verder
  alles wat je normaal genomen in een ontwikkeltraject doet.

• Als je nieuwe optie of bugfix de ultieme status bereikt heeft, dan kun
  je deze opsturen naar je eigen github repository. Maar eerst moet je
  alle tussentijdse commits samenvoegen tot een commit

  git checkout master
  git merge --squash -s subtree --no-commit -m 'De ultieme patch' nieuwetak
  

• en bevestig deze samengevoegde set

  git commit -m 'De ultieme patch' -a
  

• en stuur hem op

  git push origin master
  

Nu is de patch aangeland in de github repository. Via de web interface
kun je nu een pull request sturen naar de beheerder van de hoofd
repository van het softwareproject. Deze zal de patch beoordelen en
eventueel accepteren.

Maar, wanneer het noodlot en de beheerder wil dat je nog wat
veranderingen aan je patch aanbrengt, dan moet je met wat zaken rekening
houden. De kans is namelijk vrij groot dat het project op het internet
gewoon doorontwikkeld is en dus niet meer in lijn is met je eigen,
lokale, repository. Wanneer je nu gewoon een update (git pull) zou
doen, dan ontstaat er een conflict tussen je eigen aanpassingen en de
aanpassingen op het web. Hier dien je dus terdege rekening mee te
houden.

De juiste manier is dan ook om je lokale boom te updaten en daarna je
eigen veranderingen hier weer overheen te spoelen. Dit klinkt
omslachtig, maar kan met een commando

git pull --rebase

Als je nu weer een checkout doet van je eigen tak, dan kun je daar
verder in ontwikkelen, zonder dat er conflicten ontstaan.

git checkout nieuwetak

en na het maken van de gewenste aanpassingen weer

git checkout master
git merge --squash -s subtree --no-commit -m 'De ultieme patch MK-II' nieuwetak
git commit -m 'De ultieme patch deel 2' -a
git push origin master

Het is hierna niet nodig om een nieuw pull request te sturen, omdat
github aan de commits kan zien dat dit bij de vorige hoort. Er zal dan
ook automatisch een signaal worden gestuurd naar de beheerder van de
hoofdtak.

Op deze manier is het mogelijk om met grote groepen ontwikkelaars,
gezamenlijk aan een project te werken, zonder in elkaars vaarwater te
zitten.

Als je in het bestand ~/.gitconfig het volgende opneemt

[alias]
    timeline = log --graph \"--pretty=format:%C(192)%h%Creset by %C(bold magenta)%an%Creset (%ar)%C(182)%d%Creset%n%s%n%b\" --all

kun je met het command

git timeline

heel mooi zien hoe de takken verlopen.

Een klein voorbeeld uit de Ansible boom is

* |   611705d by Michael DeHaan (2 days ago)
|\ \  Merge pull request #2891 from glensc/make-nosetests
| | | make path to nosetests executable configurable
| * | a067877 by Elan Ruusam<C3><A4>e (2 days ago)
| | | make path to nosetests executable configurable
| | | this is to make use python2 when nosetests points to python3:
| | | 
| | | make NOSETEST=nosetests-2.7 tests
| | |      
* | |   2e2226a by Michael DeHaan (2 days ago)
|\ \ \  Merge pull request #2889 from caredotcom/newrelic_deployment_notification
| | | | newrelic_deployment notification module
| * | | 5e3ccc3 by Matt Coddington (3 days ago)
| |/ /  newrelic_deployment notification module
| | |      
* | |   de7829b by Michael DeHaan (2 days ago)
|\ \ \  Merge pull request #2888 from fabulops/campfire_notification
| | | | Campfire Notification Module
| * | | cebdcaa by Adam (3 days ago)
| |/ /  Campfire Notification Module
| | |      
* | |   cfe86be by Michael DeHaan (2 days ago)
|\ \ \  Merge pull request #2887 from caredotcom/flowdock_notification
| | | | flowdock notification module
| * | | 22ca463 by Matt Coddington (3 days ago)
| |/ /  flowdock notification module
| | |      
* | |   ec18467 by Michael DeHaan (2 days ago)
|\ \ \  Merge pull request #2886 from fesplugas/devel
| | | | Fixed Typo
| * | | 5b6087c by Francesc Esplugas (3 days ago)
| |/ /  s/temlpate/template

Onderstaand script laat op eenvoudige wijze de hierboven beschreven
werkwijze zien, door een omelet te bakken ;-)

#!/bin/bash
# vi: set sw=4 ts=4 ai:

#- Redirect stderr to stdout (just so I can use '| less')
exec 2>&1

width=80
l="$(printf "%-${width}s" "")"
l="${l// /-}"

TOP="$(pwd)"

say()
{   printf -- "\n--- %s %s\n" "${*}" "${l}" | cut -c 1-${width}
}

gitcmd()
{   printf -- "\n--- git %s %s\n" "${*}" "${l}" | cut -c 1-${width}
    git "${@}" 2>&1 | sed 's/^/        /'
    # printf -- "${l}\n"
}

rm -rf upstream developer_1 developer_2

mkdir upstream
cd "${TOP}/upstream"
say 'Creating bare repository'
gitcmd --bare init

say 'Clone into developer_1'
cd "${TOP}"
gitcmd clone upstream developer_1
cd "${TOP}/developer_1"

say 'Adding eggs'
echo 'You need eggs' > eggs
printf "\n"
gitcmd add eggs
gitcmd commit -m 'Eggs are needed for an omelette' eggs

say 'Creating omelette branch'
gitcmd checkout -b omelette

say 'Adding chives'
echo ' And chives are nice' > chives
gitcmd add chives
gitcmd commit -m 'Chives are nice' chives
#
say 'Adding seasoning'
echo 'Pepper and salt is the bare minimum' > seasoning
gitcmd add seasoning
gitcmd commit -m 'Add some flavor' seasoning

say 'Returning to master'
gitcmd checkout master

say 'Squashing omelettes'
gitcmd merge --squash -s subtree --no-commit -m 'Start of the omelette' omelette

say '-> Committing omelettes'
gitcmd commit -m 'Commit of the omelette' -a

say 'Pushing to master branch'
gitcmd push origin master

#- To the second tree --------------------------------------------------------

say 'Clone into developer_2'
cd "${TOP}"
gitcmd clone upstream developer_2
cd "${TOP}/developer_2"

say 'Adding bacon'
echo 'Bacon' > bacon
gitcmd add bacon
gitcmd commit -m 'Bacon for the flavor' bacon

say 'Adding an onion'
echo 'Onion, finely chopped' > bacon
gitcmd add bacon
gitcmd commit -m 'Onion because I like it' bacon

say 'Pushing to master branch'
gitcmd push origin master

#- Back to the original tree -------------------------------------------------

say 'Back to tree developer_1'
cd "${TOP}/developer_1"

say 'Update tree developer_1'
gitcmd pull --rebase

say 'Back to the omelette branch'
gitcmd checkout omelette

say 'Changing eggs'
echo 'You need eggs. At least two of them' > eggs
gitcmd commit -m 'Extra eggs' eggs

say 'Back to the master branch'
gitcmd checkout master

say 'Squashing omelettes with extra eggs'
gitcmd merge --squash -s subtree --no-commit -m 'Omelette with extra eggs' omelette

say 'Commit all'
gitcmd commit -m 'The new and improved omelette' -a

say 'Pushing to master branch'
gitcmd push origin master

#- Resync the second tree ----------------------------------------------------

say 'Resyncing developer_2'
cd "${TOP}/developer_2"
gitcmd pull --rebase