Benutzen Sie die Versionsverwaltung nicht nur für den Quellcode Ihres Projekts, sondern auch die Webseite, Dokumentation, FAQ, Entwurfsskizen und alles andere, was jemand vielleicht bearbeiten möchte. Behalten Sie alles direkt neben dem Quellcode, im selben Projektarchiv. Jede Information, die sich lohnt niederzuschreiben, ist es auch Wert im Projektarchiv zu sein – also jede Information die sich ändern könnte. Sachen die sich nicht ändern, sollten archiviert und nicht versioniert werden. Eine E-Mail ändert sich beispielsweise nicht, wenn sie einmal abgeschickt wurde; deshalb würde es keinen Sinn machen sie zu versionieren (es sei denn sie wird zu einem Teil eines größeren, sich entwickelnden Dokuments).

Der Grund warum es wichtig ist alles an einem Ort zu versionieren ist, dass Personen nur eine Methode lernen müssen um Änderungen einzureichen. Oftmals, wird ein Beteiligter damit anfangen Änderungen an der Webseite oder der Dokumentation zu machen, und gehen später dazu über kleine Beiträge am Quellcode zu machen. Wenn das Projekt dasselbe System für alle Beiträge verwendet, müssen Beteiligte nur eine Methode lernen. Alles zusammen zu versionieren, bedeutet auch, dass neue Funktionen gleich zusammen mit ihrer zugehörigen Aktualisierungen an der Doku eingereicht werden können, sodass ein Zweig für den Code auch ein Zweig für die Doku mit sich bringt, usw.

Behalten Sie keine generierte Dateien im Projektarchiv. Sie sind nicht wirklich bearbeitbare Daten, da sie aus anderen Daten erzeugt werden. Manche Build-Systeme erzeugen beispielsweise configure aus der Vorlage configure.in. Um eine Änderung an configure vorzunehmen, würde man configure.in bearbeiten und es daraus neu erzeugen lassen; weßhalb lediglich die Vorlage configure.in "bearbeitbar" ist. Versionieren Sie lediglich die Vorlage – wenn Sie die erzeugten Dateien auch versionieren, wird man zwangsläufig vergessen sie neu zu erzeugen nachdem man eine Änderung an einer Vorlagen eingespielt hat. Die daraus resultierende Inkonsistenz wird endlose Verwirrung stiften.^[42]

Zu der Regel, dass alle bearbeitbare Dateien im Projektarchiv sein sollten, gibt es eine Ausnahme: den Bugtracker. Eine Bug-Datenbank enthält eine Menge bearbeitbarer Daten, kann aber aus technischen Gründen diese Daten im allgemeinen nicht im Projektarchiv speichern. (Manche Tracker haben eigene primitive Funktionen zur Versionierung, die allerdings von der Versionsverwaltung des Projekts getrennt ist.)

Das Projektarchiv eines Projekts sollte per Browser erreichbar sein. Das bedeutet nicht nur die neuste Version der einzelnen Dateien einsehen zu können, sondern auch in der Zeit zurück zu gehen und frühere Revisionen der Dateien zu sehen, die Unterschiede zwischen den verschiedenen Versionen der Dateien sehen zu können, die commit-logs bestimmter Änderungen lesen zu können, usw.

Der Browser-Zugang ist wichtig, denn er bietet ein leichtgewichtiges Portal zu den Projekt-Daten. Ist der Zugriff per Browser nicht möglich, dann würde jemand, nur um eine bestimmte Datei zu untersuchen (sagen wir, um nachzuschauen ob ein bestimmter Bugfix es in den Code geschafft hat), zuerst lokal eine Versionsverwaltungs-Software installieren müssen, was eine einfache zweiminutige Anfrage zu einer halbstündigen Aufgabe macht.

Der Browser-Zugang erlaubt auch normale URLs auf bestimmte Revisionen von Dateien oder die jeweils aktuellste Revisionen. Das kann bei technischen Diskussionen sehr nützlich sein, oder falls man jemanden auf die Dokumentation verweisen will. Man könnte zum Beispiel anstatt "Eine ausführliche Anleitungen zum Fehlermanagement enthält die Datei community-guide/index.html deiner lokalen Arbeitskopie." folgendes schreiben: "Eine ausführliche Anleitungen zum Fehlermanagement kannst du unter http://subversion.apache.org/docs/community-guide/ nachlesen.", wobei die URL auf die aktuelle Version der Datei zeigt. Die URL ist überlegen: sie ist eindeutig und erübrigt die Frage, ob der Angesprochene wirklich eine aktuelle Arbeitskopie verwendet.

Manche Versionsverwaltungssysteme haben eine eingebaute Funktion um das Projektarchiv online zu durchsuchen, andere verlassen sich hierfür auf zusätzliche Software. Drei Beispiele hierfür sind ViewCVS (http://viewcvs.sourceforge.net/), CVSWeb (http://www.freebsd.org/projects/cvsweb.html), und WebSVN (http://websvn.tigris.org/). Ersteres funktioniert sowohl mit CVS als auch Subversion, das Zweite nur mit CVS und Letzteres nur mit Subversion.

Jeder Commit an das Projektarchiv sollte eine E-Mail erzeugen, die zeigt, wer den Commit gemacht hat, wann er gemacht wurde, welche Dateien und Verzeichnisse sich geändert haben und was sich an ihnen geändert hat. Die E-Mail sollte auf eine bestimmte Mailingliste gehen, eine andere als die Liste der Entwickler. Diese und andere interessierte Beteiligte sollten ermutigt werden, sich auf der Commit-Liste anzumelden, da es die effektivste Art ist sich über die Ereignisse auf Code-Ebene des Projekts auf dem Laufenden zu halten. Abgesehen von den offensichtlichen technischen Vorteilen der Überprüfung durch andere Entwickler (siehe „Code Review“), können die Commit E-Mails dazu beitragen eine Gemeinschaft aufzubauen, da sie eine gemeinsame Umgebung schaffen indem Personen auf Ereignisse (Commits) reagieren können von denen sie wissen das Andere sie auch wahrnehmen.

Wie man Commit E-Mails einrichtet, hängt von Ihrer Versionsverwaltung ab, meistens gibt es aber hierfür einen Script oder eine andere Einrichtung bei ihrer Software. Wenn Sie Schwierigkeiten bekommen es zu finden, schlagen Sie in Ihrer Dokumentation den Begriff hooks, insbesondere auch post-commit hook nach, bei CVS auch loginfo hook genannt. Diese Commit-Hooks sind eine allgemeine Möglichkeit, Befehle nach jedem Commit zu schalten. Der Hook wird von einem Commit ausgelöst, ihm werden alle Informationen über den Commit übergeben, mit denen er dann vordefinierte Aufgaben ausführen kann, wie z.B. eine E-Mail abschicken.

Bei fertig eingerichteten Systemen für Commit E-Mails werden Sie möglicherweise das übliche Verhalten ändern wollen:

Laien im Umgang mit Versionsverwaltung scheuen sich manchmal vorm Verzweigen und Zusammenführen. Das ist wahrscheinlich ein Nebeneffekt des Erfolgs von CVS: Die Schnittstellen von CVS um Zweige zu machen und wieder zusammenzuführen sind nicht ganz eingängig, weshalb viele sich angeeignet haben diese Operationen komplett zu vermeiden.

Wenn Sie zu diesen Leuten gehören, nehmen Sie sich vor alle Ängste die Sie haben mögen zu besiegen und nehmen Sie sich die Zeit um zu lernen, wie man Zweige macht und wieder zusammenführt. Es sind keine schwierigen Vorgänge, wenn man sich erst einmal daran gewöhnt hat und sie werden mit der Zeit immer wichtiger, sowie ein Projekt immer mehr Entwickler aufnimmt.

Zweige sind wichtig da sie eine knappe Ressource – den Platz im Code des Projekts – im Überfluss bereitstellt. Normalerweise arbeiten alle Entwickler im gleichen Sandkasten und bauen an der gleichen Burg. Wenn jemand eine neue Zugbrücke anbauen will, jedoch nicht alle überzeugen kann, dass es eine Verbesserung wäre, ermöglicht ein Zweig mit ihr in einer eigenen isolierte Ecke zu experimentieren. Wenn es funktioniert kann sie die anderen Entwickler einladen, sich das Ergebnis anzuschauen. Wenn alle zustimmen, dass das Ergebnis gut ist können sie mittels der Versionsverwaltung die Zugbrücke aus dem Burgflügel in die Haupt-Burg übernehmen (einen "Merge" machen).

Es ist einfach zu erkennen, wie diese Fähigkeit die gemeinschaftliche Entwicklung fördert. Menschen brauchen die Freiheit Neues auszuprobieren ohne das Gefühl zu bekommen andere bei der Arbeit zu stören. Gleichermaßen gibt es Zeiten an denen es wichtig ist, bestimmten Code von der alltäglichen Entwicklung zu isolieren, um einen Fehler zu beheben oder eine neue Version stabil zu machen (siehe „Stabilisierung einer neuen Version“ und „Wartung mehrerer Versionszweige“ im Kapitel Kapitel 7, Paket-Erstellung, Veröffentlichung, und tägliche Entwicklung ) ohne sich über ein bewegliches Ziel Gedanken zu machen.

Seien Sie großzügig bei der Nutzung von Zweigen und ermutigen Sie andere, ebenso zu verfahren. Achten Sie aber auch darauf, dass jeder Zweig nur so lange aktiv bleibt wie nötig. Jeder aktive Zweig beansprucht die Aufmerksamkeit der Gemeinschaft ein klein wenig. Selbst diejenigen die nicht an einem Zweig arbeiten, behalten noch einen groben Überblick über die Ereignisse darin. Diese Aufmerksamkeit ist natürlich wünschenswert und Commit-Nachrichten sollten auch für Zweige eingeschaltet sein, genau wie für jeden anderen Commit. Zweige sollten jedoch nicht zu einer Methode werden, die Gemeinschaft zu spalten. Mit seltenen Ausnahmen sollte jeder Zweig das Ziel haben, irgendwann wieder zurück in den Hauptzweig überzugehen und zu verschwinden.

Merges haben eine wichtige Konsequenz: Dieselbe Änderung sollte niemals doppelt committet werden. D.h. eine bestimmte Änderung sollte durch das Versionsverwaltungssystem nur genau einmal übernommen werden. Die Revision (oder die Gruppe von Revisionen) in dem diese Änderung eingebracht wurde, ist von da an seine eindeutige Kennung. Wenn sie auf weitere Zweige angewendet werden soll, sollte sie von ihrem ursprünglichen Eintrittspunkt aus in diese anderen Ziele portiert werden – man sollte also nicht mehrere textgleiche Änderungen committen, was zwar die gleiche Wirkung auf den Code haben würde, aber eine genaue Buchführung unmöglich machen würden.

Die praktische Auswirkung dieser Empfehlung sind unterschiedlich, je nach Versionsverwaltungssystem. Manche Systeme erfassen einen Merge als besonderes Ereignis, grundsätzlich unterschiedlich zu einem normalen Commit, mit eigenen Metadaten. Bei anderen wird das Ergebnis eines Merges genau wie jeder andere Commit übernommen, in solchen Fällen sollte man dafür sorgen, dass sich ein "Merge-Commit" im Commit-Log klar von einem "Änderungs-Commit" unterscheidet. In dem Commit-Log von einem Merge sollte nicht die Nachricht der ursprünglichen Änderung wiederholt werden. Stattdessen sollten Sie lediglich angeben, dass es sich um einen Merge handelt, und die Revisionsnummer der Ursprünglichen Änderung angeben und höchstens einen Satz, um die Auswirkungen der Änderung zusammenzufassen. Wenn jemand den kompletten Commit-Log sehen will, kann er die ursprünglichen Revisionen aufsuchen.

Es ist wichtig zu vermeiden, die Commit-Logs zu wiederholen, da Log-Nachrichten manchmal nach dem Commit geändert werden. Wenn die Log- Nachricht einer Änderung bei jedem Merge wiederholt würde, blieben selbst bei einer Korrektur der ursprünglichen Nachricht alle Kopien unverändert – was später unweigerlich zu Verwirrung führen kann.

Dasselbe Prinzip gilt beim Rückgängigmachen einer Änderung. Wenn eine Änderung wieder vom Code entfernt wird, sollte sein Commit-Log lediglich festhalten, dass die Änderung einer bestimmten Revision rückgängig gemacht wird und nicht eine Beschreibung der tatsächlichen Änderungen am Code, da diese Information aus der ursprünglichen Änderungen und sein Log ersichtlich ist. Selbstverständlich sollte der Log auch den Grund für die Entfernung nennen, jedoch nichts aus dem ursprünglichen Log wiederholen. Wenn möglich gehen Sie zurück und Ändern Sie den Log der ursprünglichen Änderung und weisen Sie darauf hin, dass sie zurückgedreht wurde.

Die vorhergehenden Passagen implizieren die Verwendenung einer konsistenten und gleichbleibende Syntax um auf Revisionen Bezug zu nehmen. Das ist nicht nur in den Logs hilfreich, sondern auch in E-Mails, dem Bugtracker und anderswo. Wenn Sie CVS verwenden, schlage ich "path/to/file/in/project/tree:REV" als Format vor, wobei REV eine CVS Revisionsnummer wie "1.76" darstellt. Wenn Sie Subversion verwenden, ist die übliche Syntax für die Revision 1729 "r1729" (Datei-Pfade sind bei Subversion nicht nötig, da es globale Revisionsnummern verwendet). Andere Systemen haben meistens ihre eigene übliche Syntax um Änderungen zu kenzeichnen. Konsistente Bezeichnungen erleichtern die Buchhaltung eines Projekts ungemein (was wir in Kapitel 6, Kommunikation und Kapitel 7, Paket-Erstellung, Veröffentlichung, und tägliche Entwicklung ) sehen werden und da ein großer Teil der Buchhaltung von Freiwilligen erledigt wird, muss es so einfach wie Möglich sein.

Siehe auch „Neue Versionen und tägliche Entwicklung“ im Kapitel Kapitel 7, Paket-Erstellung, Veröffentlichung, und tägliche Entwicklung .

Die meistene Versionsverwaltungen bieten Funktionen, um bestimmten Personen Schreibzugriff auf einzelne Bereiche des Projektarchivs zu erlauben oder zu verwehren. Nach dem Grundsatz, dass jemand, sobald man ihm einen Hammer in die Hand gibt, anfangen wird, überall Nägel zu sehen, wird diese Funktion von vielen Projekten benutzt, um den Beteiligten lediglich Schreibzugriff auf Bereiche zu geben mit denen sie sich offensichtlich auskennen und so sichergestellt ist, dass sie nirgendwo sonst Schreibzugriff haben. (Siehe „Committer“ im Kapitel Kapitel 8, Leitung von Freiwilligen indem beschrieben ist, wie Projekte entscheiden wer wo Änderungen machen kann.)

Mit einer solch scharfen Kontrolle können Sie wahrscheinlich kaum Schaden anrichten, eine lockerere Haltung ist aber auch in Ordnung. Manche Projekte benutzen einfach ein Vertrauenssystem: Wenn einer Person Commit-Zugriff gewährt wird, wenn auch nur für einen Teilbereich des Projektarchivs, erhält diese in Wirklichkeit den Schlüssel, um überall im Projekt zu Änderungen vorzunehmen. Sie wird einfach darum gebeten, sich auf ihren Bereich zu beschränken. Denken Sie daran, dass hierin keine echte Gefahr besteht: In einem aktiven Projekt wird sowieso jeder Commit überprüft. Wenn jemand in einem Bereich etwas ändert, in dem er nichts zu suchen hat, werden es andere bemerken und etwas sagen. Wenn eine Änderung rückgängig gemacht werden muss, ist das auch kein Problem – es ist sowieso alles in der Versionsverwaltung, also kann man es einfach rückgängig machen.

Die Sache locker anzugehen hat mehrere Vorteile. Erstens gibt es keinen weiteren Aufwand um Entwickler zusätzliche Rechte einzuräumen, sobald sie sich auf andere Bereiche ausweiten (was meistens irgendwann passiert, wenn sie länger beim Projekt bleiben). Sobald die Entscheidung getroffen wurde, kann die Person gleich anfangen Änderungen im neuen Bereich zu machen.

Zweitens kann die Erweiterung viel feiner granuliert werden. Allgemein wird ein Commit-Berechtigter im Bereich X der auch im Bereich Y arbeiten will, anfangen Patches für Y einzureichen und darum bitten, dass sie überprüft werden. Wenn jemand der bereits Zugriff auf dem Bereich Y hat solch einen Patch sieht und ihm zustimmt, können sie dem Autor einfach sagen, dass sie die Änderung gleich selber einspielen können(natürlich mit Namensangabe vom Überprüfenden bzw, Zustimmenden im Commit-Log). Auf diese Art stammt der Commit von dem, der ihn auch geschrieben hat, was sowohl aus Sicht der Informationsverwaltung als auch der Anerkennung vorzuziehen ist.

Schließlich, und das ist vielleicht das Wichtigste, regt ein System, das auf Ehre basiert, eine Atmosphäre des Vertrauens und des gegenseitigen Respekts an. Jemandem Commit-Zugriff auf einem Teilbereich zu geben, ist eine Aussage über ihre fachliche Vorbereitung – es sagt: "Wir sehen, dass du die Kenntnisse hast, um auf einem Gebiet Änderungen zu machen, also leg los". Strikte Autorisierung aufzuerlegen, sagt aber: "Wir behaupten nicht nur, dass deine Kenntnisse begrenzt sind, wir sind auch ein wenig skeptisch im Bezug auf deine Absichten". Das ist keine Behauptung, die Sie in den Raum stellen wollen, wenn es sich vermeiden lässt. Jemanden an dem Projekt als commit-berechtigt zu beteiligen, ist eine Gelegenheit, ihn in einen Kreis vertrauter Personen aufzunehmen. Das erreicht man am besten, indem man ihm mehr Macht gibt als er letztlich braucht, und ihn darüber informiert, dass es an ihm ist, sich innerhalb der genannten Grenzen zu bewegen.

Das Subversion-Projekt arbeitet schon seit vier Jahren nach dem Ehren-Prinzip, mit 33 voll -und 43 teil-berechtigten Entwicklern zum Zeitpunkt dieses Schreibens. Der einzige Unterschied, den das System macht, ist zwischen Commit-Berechtigten und nicht Commit-Berechtigten; weitere Unterteilungen bestehen allein auf zwischenmenschlicher Ebene. Dennoch hatte man dort nie Probleme mit den Grenzen der Berechtigungen. Es gab ein oder zwei Missverständnisse über das Ausmaß der Commit-Berechtigungen, die jedoch immer schnell und freundlich gelöst wurden.

Offensichtlich muss man sich auf strikte Autorisierung verlassen können, wenn Selbstkontrolle nicht sinnvoll ist. Solche Situationen sind jedoch selten. Selbst bei Unmengen Code und hunderten oder tausenden Entwicklern, sollte ein Commit zu jedem beliebigen Modul von denen zuständigen Personen überprüft werden, die auch erkennen können ob jemand an eine Stelle etwas geändert hat die er nicht sollte. Wenn Änderungen nicht regelmäßig überprüft werden, dann hat das Projekt ohnehin größere Probleme als die Commit-Berechtigung.

Insgesamt sollte man nicht allzuviel Zeit damit verbringen, die Berechtigungen der Versionsverwaltung auszutüfteln, es sei denn Sie haben einen ganz bestimmten Grund dazu. Es wird für meistens wenig handfesten Nutzen bringen und es hat seine Vorteile sich stattdessen auf menschliche Kontrolle zu verlassen.

Natürlich sollte man nichts hiervon so auffassen, dass die Beschränkungen an und für sich unwichtig sind. Es wäre schlecht für das Projekt, Teilnehmer anzuregen Bereiche zu ändern, für die sie nicht qualifiziert sind. Desweiteren geben viele Projekte dem vollen (uneingeschränkten) Zugriff auf das Projektarchiv einen besonderen Status: Es impliziert, dass der Teilnehmer das Recht hat, über Fragen die das ganze Projekt betreffen abzustimmen. Dieser politische Aspekt der Commit-Berechtigung wird weiter in „Wahlberechtigung“ im Kapitel Kapitel 4, Soziale und politische Infrastruktur behandelt.