Mitwirkung an LinuxCNC

Das offizielle LinuxCNC git repo ist zugänglich über https://github.com/linuxcnc/linuxcnc/

Jeder kann eine schreibgeschützte Kopie des LinuxCNC-Quellbaums über git erhalten:

Wenn Sie ein Entwickler mit Schreibrechten (genannt "push" in Anlehnung an das git-Kommando) sind, folgen Sie den Anweisungen in github, um ein Repository einzurichten, von dem aus Sie pushen können.

Beachten Sie, dass der Clone-Befehl das lokale LinuxCNC Repo in ein Verzeichnis namens linuxcnc-dev legt, anstatt des Standardverzeichnisses linuxcnc. Dies wurde so gewählt, da die LinuxCNC-Software standardmäßig die Configurations-Dateien (.ini) und G-Code-Programme in einem Verzeichnis in dem Pfad $HOME/linuxcnc erwartet. Dies soll Verwirrungen zwischen der Entwickung im Git Repository und der Ausführung helfen zu vermeiden.

Problem-Meldungen (engl. issues) und Anforderungen zur Integration eigener Änderungen (genannt pull requests, kurz: PR) sind auf GitHub willkommen: https://github.com/LinuxCNC/linuxcnc/issues https://github.com/LinuxCNC/linuxcnc/pulls

Wir verwenden die hier beschriebenen Git-Workflows "merging upwards" und "topic branches":

https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html

Wir haben einen Entwicklungszweig namens master und einen oder mehrere stabile Entwicklungszweige (engl. branches) mit Namen wie 2.6 und 2.7, welche die Versionsnummer der daraus jeweils hervorgehenden Veröffentlichung angeben.

Fehlerbehebungen gehen in den ältesten anwendbaren stabilen branch, und dieser branch wird in den nächst neueren stabilen branch zusammengeführt, und so weiter bis zu master. Der Committer des Bugfixes kann die Zusammenführung selbst durchführen, oder sie jemand anderem überlassen.

Neue Funktionen gehen im Allgemeinen in den "Master"-branch, aber einige Arten von Funktionen (insbesondere gut isolierte Gerätetreiber und Dokumentationen) können (nach dem Ermessen der Verantwortlichen für den stabilen branch) in den stabilen branch wandern und dort zusammengeführt werden, genau wie Bugfixes.

Es gibt viele ausgezeichnete, kostenlose Git-Tutorials im Internet.

Die erste Anlaufstelle ist wahrscheinlich die Manpage "gittutorial". Auf diese Manpage kann man zugreifen, bspw. durch die Ausführung von "man gittutorial" in einem Terminal (wenn man die git-Manpages installiert hat, bei Debian im Paket "git-man"). Das gittutorial und die dazugehörige Dokumentation sind auch hier online verfügbar:

Eine ausführlichere Dokumentation von Git finden Sie in dem Buch "Pro Git": https://git-scm.com/book

Ein weiteres Online-Tutorial, das empfohlen wurde, ist "Git for the Lazy": https://wiki.spheredev.org/index.php/Git_for_the_lazy

Halten Sie Ihre Commits klein und auf den Punkt. Jeder Commit sollte eine logische Änderung am Projektarchiv bewirken.

Halten Sie die Commit-Meldungen etwa 72 Spalten breit (damit sie in einem Terminalfenster mit Standardgröße nicht umbrechen, wenn sie von git log angezeigt werden).

Verwenden Sie die erste Zeile als Zusammenfassung der Absicht der Änderung (fast wie die Betreffzeile einer E-Mail). Danach folgt eine Leerzeile und dann eine längere Nachricht, in der die Änderung erläutert wird. Beispiel:

Fehlerbehebungen sollten im ältesten anwendbaren branch durchgeführt werden. Neue Funktionalität sollte in den Master-Zweig kommen. Wenn Sie sich nicht sicher sind, wo eine Änderung hingehört, fragen Sie im IRC oder auf der Mailingliste.

Organisieren Sie Ihre Änderungen gegebenenfalls in einem Zweig (engl. branch, eine zusammengehörige Folge von Commits), wobei jeder Commit ein logischer Schritt auf dem Weg zum endgültigen Ziel ist. Beispielsweise sollten Sie zunächst einen komplexen Code in eine neue Funktion umwandeln. Beheben Sie dann in einem zweiten Commit einen zugrunde liegenden Fehler. Dann, im dritten Commit, fügen Sie eine neue Funktion hinzu, die durch das Refactoring einfacher geworden ist und die ohne die Behebung des Fehlers nicht funktioniert hätte.

Das ist hilfreich für die Prüfer, denn es ist einfacher zu sehen, dass der Schritt "Code in eine neue Funktion umwandeln" richtig war, wenn keine anderen Änderungen darin enthalten sind; es ist einfacher zu sehen, dass der Fehler behoben ist, wenn die Änderung, die ihn behebt, getrennt von der neuen Funktion ist; und so weiter.

Bemühen Sie sich, dem vorherrschenden Einrückungsstil des umgebenden Codes zu folgen. Insbesondere Änderungen an Leerzeichen erschweren es anderen Entwicklern, Änderungen im Laufe der Zeit zu verfolgen. Wenn eine Neuformatierung des Codes erforderlich ist, sollten Sie diese getrennt von semantischen Änderungen vornehmen.

Der Test "retval < 0" sollte Ihnen bekannt vorkommen; es ist die gleiche Art von Test, den Sie im Userspace (gibt -1 für Fehler zurück) und im Kernelspace (gibt -ERRNO für Fehler zurück).

Mit Git ist es möglich, jede Bearbeitung und jeden Fehlstart als separaten Commit aufzuzeichnen. Dies ist sehr praktisch, um während der Entwicklung Kontrollpunkte zu setzen, aber oft möchte man diese Fehlstarts nicht mit anderen teilen.

Git bietet zwei Möglichkeiten, die Historie zu bereinigen, die beide frei durchgeführt werden können, bevor Sie die Änderung freigeben:

Mit git commit --amend können Sie zusätzliche Änderungen an dem letzten Commit vornehmen und optional auch die Commit-Nachricht ändern. Benutzen Sie dies, wenn Sie sofort merken, dass Sie etwas in der Commit-Nachricht vergessen haben, oder wenn Sie sich in der Commit-Nachricht vertippt haben.

Mit git rebase --interactive upstream-branch können Sie jeden Commit, den Sie seit dem Abzweig (engl. fork) Ihres Entwicklungszweigs vom Upstream-Branch (der Zweig im repository von dem Sie abgezweigt sind) gemacht haben, zurückgehen und dabei möglicherweise Commits bearbeiten, Commits verwerfen oder mit anderen Commits zusammenlegen (Squash). Rebase kann auch verwendet werden, um einzelne Commits in mehrere neue Commits aufzuteilen.

Wenn Ihre Änderung aus mehreren Patches besteht, kann git rebase -i verwendet werden, um diese Patches in eine Folge von Commits umzuordnen, die Schritte Ihrer Arbeit klarer darstellt. Eine mögliche Folge des Umordnens solcher Patches ist, dass man Abhängigkeiten falsch einordnen kann - zum Beispiel, wenn man die Verwendung einer Variable einführt und die Deklaration dieser Variable erst in einem späteren Patch folgt.

Beim Bauen des HEAD branches würde in einem solchen Fall nicht jeder Commit gebaut. Das machte dann git bisect kaputt - etwas, das jemand anderes später benutzen könnte, um den Commit zu finden, der einen Fehler eingeführte. Es ist also nicht nur wichtig, sicherzustellen, dass Ihr Zweig gebaut wird, sondern auch, dass jeder einzelne Commit erfolgreich kompiliert.

Es gibt einen automatischen Weg, einen Zweig darauf zu prüfen, ob jeder Commit baubar ist - siehe https://dustin.sallings.org/2010/03/28/git-test-sequence.html und den Code unter https://github.com/dustin/bindir/blob/master/git-test-sequence. Verwenden Sie wie folgt (in diesem Fall testen Sie jeden Commit von origin/master bis HEAD, einschließlich der Durchführung von Regressionstests):

Dies meldet entweder All is well (engl. für Alles in Ordnung) oder Broke on <commit> (engl. für Fehler bei <commit>)

Bitte verwenden Sie die Möglichkeit Dateien umzubenennen mit Bedacht. Wie bei der Einrückung einzelner Dateien erschweren auch Umbenennungen die Verfolgung von Änderungen im Laufe der Zeit. Zumindest sollten Sie im IRC oder auf der Mailingliste einen Konsens darüber finden, dass die Umbenennung eine Verbesserung darstellt.

Verwenden Sie git pull --rebase anstelle von git pull, um eine schöne lineare Historie zu erhalten. Wenn Sie rebasen, behalten Sie Ihre Arbeit immer als Revisionen, die vor origin/master liegen, so dass Sie Dinge wie git format-patch ausführen können, um Entwicklungen mit anderen zu teilen, ohne sie in das zentrale Repository zu pushen.