doc/wiz/gerrit-workflow

Typischer Arbeitsablauf
***********************

(Es gibt andere Arbeitsweisen, aber dies hier ist eine, die sich
bewaehrt hat.)

Nehmen wir an, ich moechte etwas neues einbauen, einen Bug fixen etc.
Alle der folgenden Schritt werden auf eurem eigenen Rechner in eurem
lokalen Clone des jeweiligen Repositories durchgefuehrt.

1. Repository clonen und/oder updaten

   Zuerst einmal wird ein checkout des Zweiges 'master' gemacht. Und
   in diesen Zweig hol ich mir erstmal den aktuellen Stand aus dem Mud
   (pull).

   Jetzt moechte ich alle Aenderungen erstmal in einem separaten Zweig
   machen. Warum? Weil dann der 'master' (das ist der aktive Zweig im
   Mud!) immer in einem benutzbaren Zustand ist. Desweiteren kann man
   einen Zweig einfach wegwerfen, wenn irgendwas groesseres
   schiefgelaufen ist... Ausserdem ist es dann einfacher,
   zwischenzeitliche Aenderungen aus dem Mud zu integrieren.

2. Neuen Zweig erstellen

      git checkout -b neue_kampftaktik

   Hiermit wird  ein neuer Zweig erstellt und gleichzeitig in ihn
   gewechselt.

   Hier mach ich jetzt alle moeglichen Arbeiten und Basteleien, die
   ich fuer die neue Kampftaktik brauche. Tipps dazu:

      * Viele und haeufige Commits machen! Je kleiner einzelne
        Commits sind, desto besser kann man Aenderungen spaeter
        verfolgen (was z.B. super ist, wenn jemand was abnehmen muss!)
        und desto besser kann man einzelne Aenderungen spaeter bei
        Bedarf auch rueckgaengig machen, wenn man merkt, dass man
        stellenweise Unsinn gebaut hat. ;-)

      * Thematisch unterschiedliche Dinge in verschiedene Commits
        packen. Also z.B. erst Syntaxfehler editieren und commiten,
        dann eine neue Methode fuer etwas ganz andere schreiben und
        commiten.

3. Aenderungen pruefen und commiten

   Hiermit lasse ich mir anzeigen, welche Dateien nicht-committete
   Aenderungen enthalten (oder neu sind/geloescht wurden):

      git status

   Dies zeigt mir alle nicht-committeten Aenderungen an - zeilenweise
   verglichen mit dem vorherigen Zustand:

      git diff

4. Aenderungen in lokales Repository commiten

   Hiermit merke gemachten Aenderungen fuer den naechsten Commit vor.
   Ich kann hier einzelne Dateien auswaehlen, bestimmte Dateien oder
   sogar nur bestimmte Teile der Aenderungen in einer Datei. (Hierzu
   bitte die Git-Doku bemuehen.):

      git add <file>             // einzelne Files auswaehlen
      git add -A ./              // alle Files auswaehlen

   Hiermit erstelle ich einen Commit, der die bisherigen Aenderungen
   umfasst. Dabei wird ein Editor geoeffnet, in den ich eine
   informative Nachricht ueber meine Aenderungen hinterlassen kann.
   Das ist besonders wichtig, wenn ich in fremden Gebieten arbeite,
   aber auch fuer mich und einen etwaigen abnehmenden Magier sehr
   sinnvoll. Anregung: Die erste Zeile ist das sog. Betreff des
   Commits - vergleichbar mit dem Betreff einer eMail. (bitte nur so
   50-60 Zeichen). Anschliessend muss eine leere Zeile folgen und
   danach eine laengere Beschreibung eingeben werden:

      git commit

   Wenn ich an diesem Punkt mit dem Bugfix oder Feature noch nicht
   fertig bin: einfach den Schritt 4 beliebig oft wiederholen, d.h.
   beliebig viele weitere Commits machen.

5. Aenderungen in lokalen Master-Zweig mergen

   Bin ich dann schliesslich aber mal fertig, gehe ich erstmal zurueck
   zum master-Zweig:

      git checkout master

   Huch! Ploetzlich sind alle Dateien auf dem alten Stand! Keine
   Sorge, unsere Aenderungen sind im Zweig 'neue_kampftaktik' sicher
   verwahrt.

   Achtung: wenn ihr mit anderen zusammen arbeitet, koennte jemand
   anderes im MUD Aenderungen vorgenommen haben. Ein einfaches "git
   pull" um die Dateien im 'master'-Zweig auf den neuesten Stand zu
   bringen, zeigt euch auch Aenderungen. Wenn da jetzt "Already up-to-
   date." steht, ist alles in Butter, ansonsten siehe unten.

   Mit diesem Kommando hole ich nun alle Aenderungen aus meinem Zweig
   'neue_kampftaktik' in den Zweig 'master' (merge):

      git merge neue_kampftaktik

6. Aenderungen in das MUD-Repository uebertragen

   Jetzt bin ich bereit, die Aenderungen ins Mud zu uebertragen:

      git push origin <lokaler_zweigname>:<zweigname_im_mg>

   Job done! (Hinweis: nur der Branch "master" wird ins Mud selber
   synchronisiert, alle

      anderen Zweige existieren nur in den git-Repositories.)


Sonderfaelle und erweiterte Moeglichkeiten
==========================================

1. Zwischenzeitliche Aenderungen im MUD beruecksichtigen

      Es koennte sein, dass man fuer den Branch ne ganze Weile
      gebraucht hat - und dass waehrend meiner Arbeit jemand anders
      Aenderungen (im Mud oder Repo) gemacht hat.

      Diese Aenderungen sollte man sich wie geschrieben als erstes
      nach dem Umschalten zum master-Zweig holen:

         git pull

      Jetzt geh ich wieder in meinen Zweig (ohne -b):

         git checkout neue_kampftaktik

      und mache ein sog. Rebase. Damit verschiebe ich sozusagen, den
      Punkt, an dem mein Zweig vom 'master' abzweigt und tue so, als
      ob die eben geholten Aenderungen schon da gewesen waeren, als
      ich den Zweig erstellte. (Andere Sichtweise: ich nehme meine
      Zweig und setz ihn auf den aktuellen

   'master' dran.):

        git rebase master

      Der Vorteil ist: wenn jetzt was kaputt gegangen ist, es also Konflikte gibt,
      dann gibt es die nur in meinem Zweig 'neue_kampftaktik' und dort kann ich
      sie in aller Ruhe reparieren. Sowohl der 'master' im MUD als auch mein
      lokaler 'master' sind intakt.

      Und jetzt geht es wie oben weiter.


SIEHE AUCH
==========

   * gerrit

   * Doku von Gerrit:

     * *https://mg.mud.de/gerrit/Documentation/intro-user.html*

     *
       *https://mg.mud.de/gerrit/Documentation/index.html#_tutorials*

   * git-howto: Wie git benutzt wird

   * git-kooperation: Ein ueber git-workflow hinausgehendes Beispiel
     zur Synchronisation bzw Kooperation mehrerer Magier/Rechner

   * gerrit-sync: Wie die Synchronisierung zw. git-Repos und Mudlib
     ablaeuft

   * git-faq: haeufig gestellte Fragen/Probleme