OpenSource: Wie starte ich mein Projekt richtig?
Vor einiger Zeit habe ich mein erstes OpenSource-Projekt veröffentlicht. In diesem Artikel erkläre ich grob, welche Punkte man bei der Veröffentlichung beachten sollte. Es werden noch weitere Artikel folgen. In diesen gehe ich dann auf einige in diesem Artikel erwähnten Punkte genauer ein und zeige im Detail wie eine technische Umsetzung aussieht.
Um was geht es?
Für diesen Blog wollte ich keine Wordpress-Monster und Konsorten verwenden. Also habe ich mich nach leichtgewichtigen Blog-Engines umgeschaut und nicht nach einer eierlegenden Wollmilchsau, welche zusätzlich Theming, Templating und zig andere Features beinhaltet. Hierfür wollte ich einfach express.js nutzen. Eine Blog-Engine soll lediglich meine Artikel indizieren und mir eine einfach Möglichkeit bieten auf diese zuzugreifen. Alles was ich nun aber gefunden hatte war für meine Bedürfnisse entweder zu kompliziert, zu überfüllt oder nicht gut erweiterbar. Dann hatte ich den Entschluss gefasst mir selbst eine kleine Engine zu schreiben, genau wie ich sie mir vorstelle und sie dann als OpenSource-Projekt zu veröffentlichen. So kann ich nach jahrelanger Nutzung von OpenSource-Software der Community auch mal etwas zurückgeben.
bloggy
Die oben angesprochene Engine habe ich bloggy genannt. Es handelt sich um ein Node.js-Projekt. Die meisten Punkte in diesem Blog-Artikel sind aber von der Programmiersprache unabhängig und auch für kommerzielle Closed-Source-Projekte gültig. Mehr Worte will ich über bloggy hier nicht verlieren. Das kann jeder selbst auf GitHub nachlesen, wenn er möchte.
Erfahrungen
Ich habe mir vor der Veröffentlichung von bloggy viele Punkte aus bereits erlangten Erfahrungen oder bestehenden OpenSource-Projekten abgeschaut. Des Weiteren habe ich geprüft wie und wo man sein Projekt am besten bekannt macht. Diese Erfahrungen und Punkte habe ich in diesem Artikel zusammengefasst. Genaue Implementierungen wie Continuous Integration, Grunt, Testing, usw. werden in weiteren Artikeln folgen.
Recherche
Wichtig ist zuerst zu prüfen, ob bereits ein Projekt existiert, welches das abdeckt, was du entwickeln möchtest. Es spricht nichts dagegen nochmal etwas Ähnliches zu entwickeln. Dann solltest du dir aber in etwa folgende Fragen stellen:
- Warum sollten die Leute lieber mein Projekt verwenden, als das bereits existierende?
- Was sind die Vorteile?
- Vielleicht besser erweiterbar?
- Leichtgewichtiger?
- Einfacher?
Was ist zu tun?
Die folgenden Punkte beschreiben meiner Meinung nach alle Aspekte, welche unbedingt vor dem ersten Bekanntmachen umgesetzt und beachtet werden sollten. Wenn du anderer Meinung bist oder noch etwas ergänzen möchtest, dann hinterlasse mir unten einfach einen Kommentar.
1. Projektname und Beschreibung
Einer der wichtigsten Punkte, welcher zudem häufig unterschätzt wird, ist der Name des Projekts und dessen Beschreibung. Der Name sollte am besten kurz, einfach zu merken und zu schreiben sein. Auch die Kurzbeschreibung ist sehr wichtig. Hier gilt auch das Prinzip: So wenig wie möglich, so viel wie nötig. Der Name, die Beschreibung, der Link zum Projekt und ein oder zwei Hashtags sollten locker in einen Tweet passen.
Natürlich sollte der Name auch noch nicht vergeben sein. Also zumindest nicht als OpenSource-Projekt. Außerdem sollte natürlich ein Projektname gewählt werden, welcher nicht anstößig oder beleidigend für andere Entwickler wirken könnte. Aus diesem Grund wurde der Test-Runner Testacular in Karma umbenannt. Du solltest dir von daher besser einmal mehr, als einmal zu wenig Gedanken über den Namen machen. Wenn sich tatsächlich mal irgendwann eine "Szene" um dein Projekt gebildet haben sollte, dann hindert eine späte Umbenennung auch das Wachstum und ist mit einem großen Aufwand verbunden. Zum Beispiel müssen Wikis oder Dokumentationen angepasst werden, Links zu Projektseiten gehen eventuell nicht mehr, usw.
2. Lizenz
Als nächsten Punkt sollte eine Lizenz für das Projekt gewählt werden. Die MIT-Lizenz ist sehr verbreitet und kann für den privaten und geschäftlichen Einsatz verwendet werden. Das Ändern des Quellcodes ist natürlich auch erlaubt. Eine genauere aber dennoch übersichtliche Zusammenfassung der Unterschiede zwischen den vielen verschiedenen Lizenzen gibt es auf tl;drLegal.
3. Keep it simple
Je einfacher das Framework oder die Library verwendbar ist, desto besser. Man will nicht ellenlange Dokumentationen oder Wikis durchforsten müssen. Das heißt also, dass du sprechende Klassen- und Methodennamen, Fluent Interfaces, leichtgewichtige Strukturen, usw. verwenden solltest. Versuche dich reinzuversetzen, dass ein eventueller Benutzer erst einmal keine Ahnung von deiner API hat. Versuche also die Einstiegshürde so gering wie möglich zu halten.
Auch eine Integration des Projektes sollte so einfach vonstattengehen. Für viele Plattformen existieren Packagemanager, wie zum Beispiel nuget, npm, pip, RubyGems, usw. Auch hier sollte stets die aktuellste ausführbare Version der Projektes eingepflegt werden.
4. SemVer
Bei den Versionsnummern solltest du dich bei Node.js-Projekten immer an die SemVer-Spezifikation halten. SemVer steht für Semantic Versioning und beschreibt unter anderem, wie MAJOR-, MINOR- und PATCH-Versionen vergeben werden sollten. Auch die Art der Benennung von Alpha-Versionen oder wann Breaking API-Changes erlaubt sind ist spezifiziert.
5. Readme und Code-Beispiele
Dem Projekt darf eine Readme.md im Hauptverzeichnis nicht fehlen. Diese wird bei Github und BitBucket automatisch angezeigt, wenn man sich im Projekt-Root befindet. In dieser Readme-Datei kann man nun detaillierte Infos zum Projekt hinterlegen. Was sind die genauen Vorteile? Wie starte ich die Tests? Benötige ich noch Abhängigkeiten zum Kompilieren oder Ausführen? Wenn es sich um ein kleines Projekt handelt, dann können hier auch verwendbare Klassen/Methoden dokumentiert werden. Bei größeren Projekten ist ein Wiki eventuell besser dazu geeignet.
Da Entwickler grundsätzlich keine Dokumentation lesen wollen und Zeit auch immer Mangelware ist, darf eine Quickstart-Sektion nicht fehlen. In dieser sollten alle nötigen Schritte enthalten sein, damit man das Projekt schnell verwenden kann. Am besten auch mit einem kurzen Code-Snippet. Quasi eine tl;dr, dass man sofort loslegen kann. Zusätzlich sollte auch noch ein ausführbares Beispiel in der Versionsverwaltung enthalten sein.
6. Code-Style
Wenn mehrere Leute an einem Projekt arbeiten, dann sollten gewisse Regeln definiert sein, wie der Quellcode formatiert wird. In diesen Regeln ist unter anderem festgelegt wie Variablen benannt oder Abstände eingehalten werden. Ansonsten kann es schnell zu einem inkonsistenten Code-Bild kommen. Douglas Crockford hat die Code Conventions for the JavaScript Programming Language definiert, welche sehr weit verbreitet ist. Für C# gibt es die Framework Design Guidlines.
Damit der Code-Style auf immer konsequent eingehalten wird, gibt es für viele Sprachen Tools. Für C# existiert beispielsweise StyleCop, für JavaScript JsHint das ursprünglich aus JsLint entstanden ist.
7. Tests und Code-Coverage
Tests, Tests, Tests, Tests! Wir sind professionelle Entwickler, also muss unser Projekt getestet sein. Ich will schließlich keine Komponente verwenden, bei welcher ich hoffen muss, dass sie zuverlässig funktioniert. Welches Testframework genau zum Einsatz kommt ist prinzipiell erst einmal nicht so wichtig. Am besten ein bekanntes, das ohne Probleme installiert und ausgeführt werden kann. Empfehlen würde ich NUnit für .NET und Mocha für JavaScript/Node.js.
Zusätzlich sollte auch noch die Code-Coverage berechnet werden können. Somit hat man einen groben Überblick, wieviel Prozent des Codes mit Tests abgedeckt sind. Dies gibt bei einem Ergebnis von 100% zwar keine 100%-ige Sicherheit auf Fehlerfreiheit, aber rein psychologisch auf jeden Fall ein gutes Gefühl.
8. Automatisiertes Ausführen mit Grunt oder Scripts
Im Laufe eines Projektes werden bestimmte Aufgaben, wie beispielsweise das Ausführen von Unit-Tests, Kompilieren der Anwendung, Minifying oder Bundling (Asset Management) immer wieder ausgeführt. Dafür sind teilweise mehrere einzelne Schritte notwendig. Um potentiellen Mitentwicklern am Projekt den Einstieg und die Mitarbeit zu erleichtern solltest du diesen Aufwand so gering wie möglich halten. Makefiles, Batch- oder Shell-Scripte vereinfachen diesen Aufwand enorm. Anstatt zum Beispiel fünf verschiedene Befehle muss man sich nun nur noch einen merken und diesen ausführen. Gerade bei Schritten, welche häufig verwendet werden, macht sich diese Automatisierung in kürzester Zeit bezahlt.
Speziell im Node.js-Umfeld hat sich Grunt und die Verwendung von npm etabliert. In der Datei package.json können Scripte hinterlegt werden. Somit ist ein einheitlicher Weg geschaffen, um bestimmte Aktionen anzustoßen. Auf package.json - An interactive Guide gibt es neben der Beschreibung der scripts-Sektion auch Erläuterungen zu anderen Bereichen.
9. Continuous Integration
Es muss auf jeden Fall sichergestellt sein, dass sich das Projekt immer in einem kompilierbaren Zustand befindet. Es gibt sowohl für Node.js, als auch für .NET-Projekte öffentliche Dienste, wie Travis CI oder AppVeyor, welche automatisch nach einem Check-In den Build-Prozess anstoßen. Coveralls speichert dazu einen Verlauf der Test-Abdeckung. Wenn bereits Batch- oder Grunt-Scripts existieren, dann ist das Konfigurieren des CI-Prozesses im Handumdrehen erledigt.
10. Badges
Die meisten öffentlichen CI- oder Code-Coverage-Dienste stellen sogenannte Badges bereit. Badges sind dynamische Bilder, welche man problemlos in der Readme-Datei des Projektes referenzieren kann. In diesen wird dann zum Beispiel dargestellt, ob der Build-Vorgang erfolgreich war oder wieviel Code mit Tests abgedeckt ist. Sie werden direkt in die Readme eingebunden und schaffen Transparenz für etwaige Mitentwickler oder Anwender.
11. Projekt-Hosting
Bei JavaScript-lastigen Projekten kann ich GitHub nur empfehlen. Ich würde sogar sagen, dass auch alle anderen Projekte, unabhängig von ihrer Sprache dort gut aufgehoben sind. Viele Entwickler besitzen einen GitHub-Account und haben Git sowieso auf ihrem System installiert und können so direkt loslegen. Desweiteren steht der soziale Charakter bei GitHub im Vordergrund. Man kann Projekte mit "Stars" versehen, Entwicklern folgen oder sie in Kommentaren oder Issues taggen. Aufgrund der hohen Verbreitung von Github, sind auch viele Build-Dienste darauf ausgelegt und optimiert. So kann normalerweise mit sehr geringem Aufwand eine Integration zwischen GitHub und anderen Diensten hergestellt werden.
Auf Pull-Requests von anderen Contributern wird auch der konfigurierte CI-Prozess automatisch angewandt. Somit kann man diese beruhigt akzeptieren, wenn sie erfolgreich, bzw. direkt überprüfen, warum diese nicht durchgelaufen sind.
Hier zumindest noch eine kurze Liste mit einigen OpenSource-Hostern:
12. Responsive sein
Wenn du dein Projekt nun frisch veröffentlicht hast und andere Entwickler sich dafür interessieren, dann solltest du schnell auf Fragen oder Probleme reagieren. Niemand will auf die Resonanz auf seinen Pull-Request eine Woche oder länger warten. Niemand will bei einem wichtigen Issue lange auf eine Problemlösung hoffen. Wenn das Projekt etwas "gereifter" ist, dann ist das IMO nicht mehr so kritisch, wie in der Anfangsphase.
13. Bekannt machen
Wenn du nun den Grundstein gelegt hat, du also alle Punkte von oben erfüllt, bzw. verinnerlicht hast, dann möchtst du natürlich auch eine möglichst große Masse an Entwicklern erreichen. Hierfür gibt es verschiedene Kanäle, die du verwenden kannst. Du kannst gezielt Leute per Mail benachrichtigen, einen Link auf deiner Timeline in Facebook/Twitter oder zum Beispiel auf Reddit posten. Und dann existieren noch spezielle Platformen oder News-Aggregatoren je nach Sprache.
Im Javascript-Umfeld wären das beispielsweise:
Wichtig ist, dass du nur das Nötigste in den Posts oder Tweets unterbringst. Maximal 160 Zeichen sollten ausreichen.
Fazit
Berücksichtigst du diese Liste an Punkten bei deinem OpenSource-Projekt, dann erlangt dieses einen sehr professionellen Touch. Selbstverständlich sind alle oben genannten Punkte auch für Closed-Source Projekte gültig, je nach Projektart aber vielleicht nicht so wichtig. In den nächsten paar Blog-Artikeln werde ich genauer auf die technische Implementierung eingehen. Stay tuned.
Bloggy war mein erstes OpenSource-Projekt. Was kann man noch besser machen?
Hinterlasst mir einen Kommentar oder twittert mir, falls ihr Ideen habt!