Diese Seite wurde von der Cloud Translation API übersetzt.

moja global projekt

Diese Seite enthält die Details zu einem Projekt für technische Angelegenheiten, das für die Google-Saison der Dokumente angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:: Moja global
Technischer Redakteur:: Tlazypanda
Projektname:: Dokumentation des technischen Onboarding-Leitfadens für FLINT
Projektlänge:: Standardlänge (3 Monate)

Projektbeschreibung

Dokumentation des technischen Onboarding-Leitfadens für FLINT, der neue Mitwirkende durch ein technisches Onboarding führt, damit sie mit minimaler Unterstützung der Entwickler schnell loslegen können.

Projektprobleme

Im Folgenden finden Sie eine Liste der wichtigsten Probleme im Zusammenhang mit der aktuellen Dokumentation: – Die Anleitung zur lokalen Einrichtung ist unübersichtlich, was es für neue Mitwirkende schwierig macht, loszulegen. – Mehrere Repositories von FLINT sind nicht dokumentiert und nicht miteinander verknüpft, was es für Neulinge schwierig macht, zu erkennen, welches Repository installiert werden soll. - Die Windows-Installation ist gut dokumentiert, aber die Dokumentation zur Linux-basierten Installation weist noch Verbesserungspotenzial auf. – Der Git-Workflow ist derzeit nicht Teil der Dokumentation.

Vorgeschlagene Lösung

Dieser Vorschlag enthält eine Lösung, mit der neue Mitwirkende durch ein technisches Onboarding geführt werden, damit sie mit minimaler Unterstützung von den Maintainern einfach loslegen können. Das lässt sich erreichen, indem die aktuelle Dokumentation so umgestaltet wird, dass sie für Anfänger geeignet ist, und indem ein zentrales eigenständiges Repository für die gesamte verfügbare Dokumentation eingerichtet wird. Das Projekt ist in drei Phasen unterteilt: – Vorhandene Dokumentation und Refaktorierung überprüfen: Ziel dieser Phase ist es, den aktuellen Leitfaden zu überprüfen und so zu überarbeiten, dass er prägnant und für neue Mitwirkende leicht verständlich ist. Außerdem muss die Dokumentation angepasst werden, um sie für Einsteiger zu optimieren. Dazu fügen Sie Badges, Emojis und Informationen zu Problemen hinzu, die als „Nur für Einsteiger“-Tags oder als „gutes erstes Problem“-Tags gekennzeichnet sind. – Zentrales eigenständiges Dokumentations-Repository erstellen: Ziel dieser Phase ist es, alle verfügbaren Dokumente in einer logischen sequenziellen Reihenfolge in einem eigenständigen Repository zu verknüpfen. Dazu gehören die Richtlinien für Beiträge, Anleitungen zur Projekteinrichtung und Schritt-für-Schritt-Anleitungen. – Entwickler-Workflow und Community-Website für neue Entwickler hinzufügen: Ziel dieser Phase ist es, den Entwickler-Workflow hinzuzufügen, der die Richtlinien für Git-Beiträge und die Technologiearchitektur des Projekts sowie die Test- und QA-Richtlinien enthält. Die vorgeschlagene Community-Website ist eine einseitige Anwendung, die den Workflow, erstmalige Probleme, die von den neuen Mitwirkenden geltend gemacht werden können, und eine Liste aller Mitwirkenden anzeigt. Phase 1: Vorhandene Dokumentation prüfen und Refactoring durchführen:

Ändern Sie die aktuelle Dokumentation der folgenden Repositories: - FLINT: Die aktuelle Dokumentation ist nicht sehr detailliert und enthält keine sequenzielle Reihenfolge der erforderlichen Bibliotheken. Die detaillierten Anleitungen sind in verschiedene PDFs unterteilt, können aber an einem Ort prägnanter zusammengefasst werden. Außerdem sind die Installationsanleitungen auf Windows ausgerichtet. Für die Installation unter Linux kann es jedoch vorteilhaft sein, zum FLINT.docker-Repository weitergeleitet zu werden. – FLINT.docker: In der aktuellen Dokumentation wird nicht der Zweck dieses Repositories erläutert, nämlich die Bereitstellung der Linux-Installation von FLINT über Docker. Der Support über Docker ist nur auf Ubuntu 18.04 (Bionic Beaver) beschränkt, kann aber auf andere Linux-basierte Distributionen ausgeweitet werden. Die aktuelle Dokumentation muss auch einen Schwerpunkt auf die sequenzielle Art der Einrichtung der Dockerfiles legen und genügend Informationen darüber enthalten, wie aus dem Makefile erstellt werden kann. – FLINT.example: In der aktuellen Dokumentation wird nicht der Zweck dieses Repositories erläutert, nämlich ein Beispiel für die Verwendung von FLINT zu liefern. Die verschiedenen Beispielausführungen können besser mit spezifischen Anweisungen für die Ausführung voneinander getrennt sein. Außerdem müssen wir dieses Repository mit unserem FLINT-Haupt-Repository verknüpfen, damit Nutzer hierhin navigieren können, um sich das Beispiel in Aktion anzusehen.

Der aktuellen Dokumentation müssen die folgenden Informationen hinzugefügt werden: – Verwendung von Git und GitHub: Dazu gehört eine detaillierte Anleitung zum Forken, Klonen und Festlegen des Remote-Upstreams für das Repository. Außerdem finden Sie Informationen dazu, wie Sie den Rebase auf den neuesten Master ausführen und Zusammenführungskonflikte beheben. – Badges und Emojis: Die aktuelle Dokumentation enthält keine Badges und Emojis, die neuen Mitwirkenden das Gefühl geben könnten, willkommen zu sein und die Probleme weniger abschreckend zu finden. – Informationen zu Problemen für Einsteiger: So können neue Mitwirkende zu Problemen für Einsteiger und zur Community-Website weitergeleitet werden. – Informationen zum Import-me-Repository: Das Import-me-Repository dient als Vorlage für den Einstieg in jedes Moja Global-Repository. In der aktuellen Dokumentation wird die Wichtigkeit dieser Informationen nicht erwähnt. Es muss aktualisiert werden, um das Import-me-Repository zu erwähnen. Außerdem müssen die Schritte zum Auswählen dieser Vorlage beim Erstellen eines neuen Repositorys hinzugefügt werden. Es sollte auch einen etablierten Prozess geben, mit dem Programmierer zusätzliche Funktionen für das Import-me-Repository vorschlagen können.

Phase 2: Erstellen Sie ein zentrales eigenständiges Dokumentations-Repository :

Tool, das für die Hostingplattform verwendet werden soll:

Für diese Hostingplattform wird Read The Docs aus folgenden Gründen vorgeschlagen: Bewertet hoch unter verschiedenen Hostingplattformen. – Automatische Aktualisierung beim Pushen von Commits – Einfache Einrichtung und Unterstützung bei der Fehlerbehebung aufgrund der großen Community, die es verwendet – Die Dokumentation wird mit reStructuredText formatiert und die Ausgabe wird von Sphinx kompiliert.

Ordnen Sie alle Inhalte in einer logischen Reihenfolge an:

Die vorgeschlagene Reihenfolge der Inhalte ist folgende: Einführung in die Entwicklerdokumentation: Dieser Abschnitt enthält eine Einführung in Moja Global und FLINT. – Beitragen: Dieser Abschnitt besteht aus den Unterabschnitten „Möglichkeiten zum Beitragen“ (in Bezug auf Code/Melden von Fehlern/Übersetzung/Dokumentation/Veranstaltungen organisieren usw.) und „Code of Conduct“. – Entwicklungseinrichtung: Dieser Abschnitt besteht aus den Unterabschnitten „Git- und GitHub-Workflow“, „Windows-Installation“ und „Linux-Installation“. – Entwickler-Workflow: Dieser Abschnitt enthält Informationen zu den für die Tests integrierten Tools und dazu, wie Sie manuelle Tests für Ihren Pull-Request ausführen. Weitere Informationen finden Sie in der nächsten Phase. - Mach mit: In diesem Bereich findest du verschiedene soziale Foren wie z. B. Slack-Kanäle, über die du dich mit Moja Global austauschen und zusammenarbeiten kannst.

Phase 3: Fügen Sie den Entwickler-Workflow und die Community-Website für neue Beitragende hinzu:

Dokumentation zum Entwickler-Workflow:

Die Dokumentation des Entwicklerworkflows besteht aus den folgenden Unterabschnitten:

Verwendeter Technologie-Stack/-Architektur und die verschiedenen Module im Code: Dokumentation, um die neuen Mitwirkenden mit dem implementierten Technologie-Stack sowie den verschiedenen Bibliotheken und Modulen der Codebasis vertraut zu machen.
Integrierte Test- und Abdeckungstools: Neue Nutzer, die die CI/CD-Pipeline-Tools für Tests nutzen; Abdeckungs-Bots und automatische Qualitätsprüfungen werden anhand ihres Codes ausgeführt. Außerdem sollten Sie ihnen mitteilen, an wen sie sich wenden können, wenn die Tests fehlschlagen.
Bots, die den Workflow erleichtern, z. B. Zulipbot: Entwerfen von Inhaltsvorlagen für die Bots, die angezeigt werden sollen, und Dokumentation, damit Nutzer die Bots verstehen und die Konfiguration des Bots durch eigene Beiträge sogar verbessern können.
Manuelles Testen und Einreichen eines Pull-Requests: Es muss eine Dokumentation dazu vorliegen, wie Pull-Requests manuell anhand bestimmter Standards getestet und die Ergebnisse in Form von Screenshots/GIFs beim Einreichen von Pull-Requests hochgeladen werden.
Richtlinien für die Überprüfung von Pull-Anfragen, die von Mitwirkenden befolgt werden müssen: Richtlinien zum Tagging bestimmter Teams zur Überprüfung und zum Hinzufügen von Labels wie „Prüfung erforderlich“ zur Pull-Anfrage, damit die Entwickler darauf reagieren können.

Community-Website:

Die Community-Website bietet folgende Funktionen:

Informationen zu unserem Workflow: Der Workflow besteht aus einer Reihe von Aktionen, mit denen neue Mitwirkende beginnen können, z. B. ein Problem für Erstnutzer beanspruchen, ein Problem für Erstnutzer für eine andere Person erstellen und anderen mit Feedback und der Überprüfung ihrer Pull-Anfragen helfen.
Liste der Probleme nur für Erstnutzer: Liste der Probleme, die speziell für Erstnutzer oder neue Mitwirkende gedacht sind.
Liste der in der Schwebe befindlichen Probleme: Liste der Probleme, an denen seit langem nicht gearbeitet wurde und die daher von Mitwirkenden ausgewählt werden können.
Liste der Mitwirkenden: Die Liste der Mitwirkenden, die bisher zu Moja Global-Repositories beigetragen haben.
Neueste Mitwirkende: Die Liste der Mitwirkenden, die in letzter Zeit zu Moja Global-Repositories beigetragen haben.
Links zu Chatforen: Informationen und Links zur Slack-Community, um Fragen zu klären und weitere Diskussionen zu den Projekten zu führen.