Teilen Sie:
){kind=small}
Lorna ist eine Software-Ingenieurin mit einer unheilbaren Blogging-Sucht. Sie versucht, Worte und Code gleichermaßen zu bändigen.
Verwendung der GitHub-Repository-Richtlinien zur Verbesserung der Entwicklererfahrung
Lesedauer: 3 Minuten
Bei Nexmo lieben wir es, Code mit unseren Entwicklergemeinschaften zu teilen. Normalerweise bedeutet das, dass wir den Code in einem Git-Repository auf GitHub veröffentlichen, damit jeder Entwickler, der den Code nutzen möchte, dies tun kann.
Wir haben jedoch festgestellt, dass wir jetzt etwa 300 Repositories in verschiedenen GitHub-Organisationen haben. Es kann schwierig sein, das zu finden, was man braucht, und auch zu verstehen, wie man jedes Projekt benutzt, wenn es keine gute Anleitung gibt.
Um das Entwicklererlebnis für alle noch besser zu machen, haben wir folgende Standards entwickelt (und dann öffentlich zugänglich gemacht) unsere Repository-Standards.
Wir haben drei Arten von Projekten erkannt, die wir häufig veröffentlichen, und unsere Richtlinien für jeden Typ angepasst.
Unsere SDKs sind mit Abstand die meistgenutzten Repositories und wir sind stolz auf sie! Benutzer mit unterschiedlichem Erfahrungsstand müssen in der Lage sein, diese Projekte zu nutzen und zu verstehen, wie sie sie in ihren eigenen Projekten verwenden können, um bestimmte Nexmo-Aufgaben auszuführen. Wir haben uns besonders um die Installationsanweisungen gekümmert und darauf geachtet, dass die Lizenz sehr klar ist, damit unsere Community vertrauensvoll auf unseren SDKs aufbauen kann.
Wir veröffentlichen eine Vielzahl von Demo-Applikationen. Das sind eigenständige Applikationen, die eine bestimmte Funktion von Nexmo demonstrieren, und wir stellen sie anderen zum Kopieren und Verwenden zur Verfügung. Eine klare Aussage über die Funktionen und den Zweck des Projekts ist in einem Repository wie diesem sehr wichtig. Wir haben auch an der Lizenzierung gearbeitet und daran, entweder Docker-Setups oder "Click to Deploy"-Buttons einzubauen, damit die Nutzer ausprobieren können, was wir für sie erstellt haben.
Die Gefahr bei Standards jeglicher Art ist, dass die Regeln aus dem Ruder laufen! Viele unserer Repositories sind nur eine öffentliche Version einer einmaligen Standalone-Anwendung, die zur Veranschaulichung eines Tutorials, Blogbeitrags oder Videos erstellt wurde, um Entwicklern etwas Bestimmtes zu zeigen.
Würden wir nur die veröffentlichen, die perfekt beschrieben sind, mit Funktionen zur Bereitstellung und detaillierten Anweisungen zur Verwendung, gäbe es viel weniger Repositories auf unserem GitHub Account!
Tatsächlich ist die einzige Regel hier, dass das Repository einen README enthalten muss, das einen Link zu der Sache enthält, für die es steht.
Wir haben die Repository Standards ins Leben gerufen, um eine gemeinsame Checkliste der Dinge zu erstellen, die wir für wichtig halten, wenn wir ein Repository veröffentlichen. Jeder hatte seine eigenen Ideen, aber in einem Team, das hauptsächlich aus Ingenieuren besteht, führte das nicht immer zu einer hervorragenden Leistung, wenn es um Dinge ging, die nicht zum Code gehören.
Durch die Erstellung von Checklisten und Vorlagen für die gängigsten Dinge haben wir aus "Do The Right Thing" eine "Do The Easy Thing"und verbesserten die Erfahrung von Entwicklern, die unsere Projekte auf GitHub finden.
Wir begannen mit einer einfachen README-Vorlage um eine einfache Struktur zu schaffen und uns daran zu erinnern, auf die Entwicklerdokumentation zu verweisen und den Benutzern mitzuteilen, wie sie bei Bedarf Kontakt aufnehmen können. Es ist einfach, aber viel besser als nichts.
Jedes Repository braucht eine Lizenz, und wir verwenden standardmäßig MIT. Die Richtlinien, einschließlich einer Checkliste, erinnern uns daran, dass wir das tun wollen.
Wir haben auch eine grundlegende CONTRIBUTING Datei - sie ist unvollständig, weil sie schwer zu verallgemeinern ist, aber sie gibt uns einen Ausgangspunkt und nimmt den Erstellern von Repositorys ein wenig Arbeit ab, wenn sie Code freigeben wollen.
Die Details hier sind nur kleine Dinge, und es gibt noch viel mehr Dinge in den vollständigen Richtlinien - aber Details sind wichtig. Entwickler landen möglicherweise auf Ihren GitHub-Repositories, ohne zu wissen, was sie gefunden haben oder wohin sie als nächstes gehen sollen. Wenn Sie ihnen helfen, sich zu orientieren, wo sie sich befinden, worum es in diesem Repository geht und wohin sie als Nächstes gehen könnten, sind das alles gute Zutaten für eine bessere Developer Experience.