README – gewusst wie

README Dateien haben in Softwareprojekten eine lange Tradition. Diese ursprünglich reinen Textdateien enthielten Lizenzinformationen und Anweisungen wie aus dem Quellcode das entsprechende Artefakt kompiliert werden konnte oder aber wichtige Hinweise zu Installation des Programms. Es gibt keinen wirklichen Standard wie man eine solche README Datei aufbauen sollte.

Seit dem GitHub (2018 von Microsoft übernommen) als kostenfrei Code Hosting Plattform für Open Source Projekte seinen Siegeszug angetreten ist, gab es schon recht früh die Funktion, dass die README Datei als Startseite des Repositories anzuzeigen. Dazu muss lediglich eine einfach Textdatei mit der Bezeichnung README.md im Hauptverzeichnis des Repository erstellt werden.

Um die README Dateien übersichtlicher strukturieren zu können wurde eine Möglichkeit für eine einfache Formatierung gesucht. Schnell hatte man sich für die markdown Notation entschieden, da diese einfach zu nutzen ist und auch recht performant gerendert werden kann. Somit sind die Übersichtsseiten besser für Menschen zu lesen und können als Projekt Dokumentation genutzt werden.

Es ist möglich mehrere solcher markdown Dateien als Projektdokumentation miteinander zu verknüpfen. Somit erhält man eine Art Mini WIKI das im Projekt enthalten ist und außerdem auch über Git versioniert wird.

Das ganze wurde so erfolgreich, das Selfhosting-Lösungen wie GitLab oder das kommerzielle BitBucket diese Funktion ebenfalls übernommen haben.

Nun stellt sich aber die Frage welche Inhalte man am besten in solch eine README Datei schreibt, damit diese für Außenstehende auch einen wirklichen Mehrwert darstellen. Dabei haben sich im Laufe der Zeit folgende Punkte etabliert:

  • Kurzbeschreibung des Projektes
  • Bedingungen unter denen der Quellcode verwendet werden darf (Lizenz)
  • Wie ist das Projekt zu verwenden (z.B. Anweisungen zum Compilieren oder wie wird die Bibliothek in eigene Projekte eingebunden)
  • Wer sind die Autoren des Projekte und wie kann man sie erreichen
  • Was ist zu tun wenn man das Projekt unterstützen möchte

Mittlerweile sind sogenannte Badges (Sticker) sehr populär. Diese referenzieren oft auf externe Dienste wie beispielsweise der freie Continuous Integration Server TravisCI. Diese helfen ausstehenden die Qualität des Projektes zu beurteilen.

Auf GitHub gibt es auch diverse Vorlagen für README Dateien. Man muss allerdings auch ein wenig auf die tatsächlichen Gegebenheiten des eigenen Projektes schauen und beurteilen welche Information für Nutzer bzw. Anwender wirklich relevant sind. Solche Vorlagen helfen aber sehr dabei herauszufinden ob man möglicherweise eine Punkt übersehen hat.

Das mittlerweile ziemlich jeder Hersteller von Source Control Management Serverlösungen die Funktion die README.md Datei als Projektstartseite für das Code Repository anzuzeigen integriert hat, bedeutet das eine README.me auch für kommerzielle Projekte eine sinnvolle Sache sind.

Auch wenn der Syntax für markdown leicht zu erlernen ist kann es bei umfangreichen Editierungen solcher Dateien durchaus komfortabler sein direkt eine MARKDOWN Editor zu nutzen. Dabei sollte man darauf achten, das die Vorschau auch korrekt dargestellt wird und nicht nur ein einfaches Syntaxhighligting angeboten wird.

Links sind nur für eingeloggte Nutzer sichtbar.

Links sind nur für eingeloggte Nutzer sichtbar.

README – gewusst wie

README Dateien sind Textdateien und sind in der markdown Notation formatiert. Das Code Hosting Portal…

Das Gesetz von Conway

Da der zuerst gewählte Entwurf fast nie der bestmögliche ist, muss man möglicherweise das vorherrschende…

Versionsnummern Anti-Patterns

In diesem Artikel werden einige Best Practices für die Arbeit mit Versionsnummern für Software-Artefakte diskutiert…

Automatisierungsmöglichkeiten im Software-Konfigurations-Management

Die Software-Entwicklung bietet einige äußerst effiziente Möglichkeiten, wiederkehrende Handgriffe durch Automatisierung zu vereinfachen. Das Wegfallen…

Das Neueste wird nicht immer das Beste sein

Worauf sollte man im kommerziellen Umfeld achten damit Softwareupdates nicht zu einem Problem werden? Continue…

Prozesslandschaften

Sämtlich in einem Unternehmen aufgestellten Regeln und durchgeführten Aktivitäten stellen Prozesse dar. Deswegen kann auch…

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert