📖 gget - Ressourcen zu Code-Dokumentation, Contributing Guides und Verhaltenskodizes
Wer möchte, dass andere sinnvoll zum eigenen Code beitragen und die Software verbessern, tut gut daran, potenzielle Contributors an die Hand zu nehmen.
Mit ihrem Projekt gget, einer Software zum Handling großer genomischer Datenbanken, tut Laura Luebbert genau das. In diesem Beitrag zeigen wir euch, welche Maßnahmen im Fall von gget ergriffen wurden – und auch für viele andere FOSS-Projekte von Interesse sind!
Contributing Guide
In einem Contributing Guide wird zusammengefasst, was Beitragende beachten sollen: Von der Erstellung eines Issues oder Pull Requests bis zum Merge sind bei gget alle Schritte abgedeckt.
Der Guide beinhaltet auch Hinweise zur Überprüfung des eigenen Codes vor dem Pull Request, sogar inklusive einer Vorgabe für die Formatierung.
Übrigens: Auch bei GitHub finden sich Tipps zum Erstellen von Guidelines für Contributors.
Code of Conduct
Damit Beitragende nicht nur wissen, was die technischen Ansprüche sind, sondern auch welche Werte in der Community von Bedeutung sind, gibt es bei gget einen Code of Conduct, den alle Personen befolgenbefolgen sollen, die sich dem Projekt anschließen, mit dessen Mitgliedern interagieren oder in seinem Namen kommunizieren.
Er beinhaltet neben den Werten der Community auch konkrete Beispiele für unangebrachtes Verhalten, verdeutlicht, welche Folgen dieses mit sich bringt und wer in der Verantwortung steht, die Regeln des Codes of Conduct durchzusetzen.
Code-Dokumentation
Code-Dokumentation
Ein weiterer Punkt, auf den viel Wert gelegt wurde, ist die Code-Dokumentation. In ihrer Doktorarbeit hat Laura unter anderem ein Kapitel für das Schreiben leicht nutzbarer Software veröffentlicht. Zum Thema Dokumentation finden sich darin diese Hinweise (mit Bezug auf gget):
“Erstellung einer verständlichen und schlüssigen Dokumentation auf verschiedenen Wegen:
Wegen:
- Bereitstellung von Funktionsbeschreibungen in Python/R/etc.
- Hinzufügen von Hilfemöglichkeiten (-h / --help) zu Shell-Skripten
- Schreiben eines GitHub README, das die Dokumentation enthält oder auf sie verlinkt
- Schreiben einer ausführlichen Dokumentation, die eine Installationsanleitung und
idealerweise eine "Schnellstart"-Anleitung [...] enthält
- Verfassen von Tutorials für verschiedene Anwendungsfälle der Software, idealerweise in Form von sofort ausführbaren Google Colab-Notebooks, und Verlinkung in der
Dokumentation
- Um die Zugänglichkeit zu verbessern, Alt-Text für Bilder verwenden und Dokumentation
in verschiedenen Sprachen, z. B. Englisch und Spanisch, bereitstellen”
Die kompletten Guidelines finden sich hier (S. 7-8).
WerftWerft gern einen Blick in die vielfältigen Ressourcen von gget und lasst euch für eure eigenen Projekte inspirieren!