Dieser Leitfaden richtet sich an Personen, die zum Open-Source-Projekt Discourse beitragen möchten. Er beschreibt die Einrichtung und die notwendigen Konventionen für eine effektive Zusammenarbeit.
Erforderliches Benutzerniveau: Jeder kann Code beitragen, aber Sie sollten mit Ruby und JavaScript vertraut sein.
Zusammenfassung
Diese Dokumentation behandelt folgende Punkte:
- Einrichten Ihrer Entwicklungsumgebung
- Verstehen, wo Sie mit dem Beitragen beginnen können
- Erstellen und Arbeiten mit Discourse-Plugins
- Beitrag zum Discourse-Kern
- Einhaltung der Programmierkonventionen
- Einreichen Ihrer Beiträge auf GitHub
Einrichten der Entwicklungsumgebung
Bevor Sie mit dem Beitragen beginnen, stellen Sie sicher, dass Ihre Entwicklungsumgebung korrekt eingerichtet ist. Befolgen Sie die entsprechende Anleitung für Ihre Plattform:
- Alle Plattformen: Discourse für die Entwicklung mit Docker installieren
- Mac OS X: Anleitung für Anfänger zur Installation von Discourse unter macOS für die Entwicklung
- Linux (Ubuntu): Anleitung für Anfänger zur Installation von Discourse unter Ubuntu für die Entwicklung
- Windows: Anleitung für Anfänger zur Installation von Discourse unter Windows 10 für die Entwicklung
Wo man anfangen soll
Discourse ist ein großes Projekt, und das Verständnis seiner zugrunde liegenden Technologien wie Ruby und JavaScript ist unerlässlich. Für eine Anleitung zum Einstieg lesen Sie bitte den Leitfaden für Neulinge.
Erstellen und Arbeiten mit Plugins
Plugins bieten eine Möglichkeit, die internen Abläufe von Discourse in überschaubaren Teilen zu verstehen und ermöglichen Ihnen einen einfachen Einstieg in den Beitrag von Code. Beginnen Sie mit:
- Developing Discourse Plugins - Part 1 - Create a basic plugin
- (deprecated) Plugin outlet locations theme component
Als Inspiration können Sie beliebte Ideen in #feature und #plugin:extras erkunden.
Beitrag zum Discourse-Kern
Der Discourse-Kerncode wird im Core-Repository auf GitHub verwaltet.
Unterzeichnen der CLA
Lesen und unterzeichnen Sie vor dem Beitragen die Electronic Discourse Forums Contribution License Agreement. Das Team kann keine Pull Requests (PRs) von Benutzern rechtlich akzeptieren, die die CLA nicht unterzeichnet haben.
Sich mit Starter-Aufgaben aufwärmen
Erkunden Sie das Tag pr-welcome für gute Aufgaben für den Anfang.
Bearbeiten der Fehlerliste
Beheben Sie Fehler aus der Liste der offenen Fehler, sortiert nach Likes. Hinterlassen Sie eine Notiz, wenn Sie an einem Fehler arbeiten – wenn Sie ihn nicht fertigstellen, hinterlassen Sie alle relevanten Notizen für jemand anderen, um Ihre Arbeit fortzusetzen.
Hilfe bei Feature-Themen
Tragen Sie Details und Mockups zu Feature-Anfragen bei, um deren Genehmigungsprozess zu unterstützen. Denken Sie daran, nicht jedes Feature wird im Kern enthalten sein.
Leistung verbessern
Wir freuen uns über Pull Requests, die die Client- oder Server-seitige Leistung verbessern, wobei der Schwerpunkt auf Bereichen mit hoher Auswirkung wie dem anfänglichen Laden der Startseite oder der Themenansicht liegt.
Verbesserung der von Discourse gewarteten Projekte
Tragen Sie zu anderen Open-Source-Projekten bei, die von Discourse gewartet werden. Zu den bemerkenswerten Projekten gehören:
- Logster - Web-GUI-Protokollanzeige
- Message Bus - Engine für Live-Site-Interaktionen
- Rack Mini Profiler - Diagnosewerkzeug
- Discourse API - API-Konsument
- Discourse Docker - Discourse-Verbreitungs-Engine
- WP Discourse - WordPress-Plugin
- Memory Profiler - Profiler für Ruby
- Ember Performance - Ember-Leistungstestsuite
Programmierkonventionen
Namensgebung ist ENTSCHEIDEND
Streben Sie 100%ige Übereinstimmung zwischen den auf der Website verwendeten Begriffen und den Namen von Klassen und Spalten in der Datenbank an (z. B. „posts“).
Kompatibilität mit den neuesten Versionen von Abhängigkeiten ist ENTSCHEIDEND
Stellen Sie die Kompatibilität mit den neuesten stabilen Versionen von Bibliotheken wie Rails, Ruby und Ember sicher. Testen Sie auf Regressionen, wenn Sie Abhängigkeiten aktualisieren.
Nur Test-Beiträge sind willkommen
Testbeiträge sind willkommen, insbesondere für nicht getestete Prozesse und Controller-Aktionen. Vermeiden Sie Mocking, es sei denn, es ist absolut notwendig.
Nur Refactoring-Beiträge sind NICHT willkommen
Vermeiden Sie das Einreichen von Pull Requests, die nur Refactoring beinhalten. Beheben Sie stattdessen einen Fehler oder implementieren Sie eine Funktion, während Sie den Code verbessern.
Einreichen von Code auf GitHub
Schritt-für-Schritt-Ablauf
-
Klonen Sie das Discourse-Repository:
git clone https://github.com/discourse/discourse.git -
Erstellen Sie einen neuen Branch:
cd discourse git checkout -b new_discourse_branch -
Codieren:
- Halten Sie sich an die bestehenden Code-Konventionen, die Sie im Code finden.
- Fügen Sie Tests hinzu und stellen Sie sicher, dass sie erfolgreich sind.
- Verweisen Sie auf relevante Diskussionen im Discourse Meta Forum.
-
Befolgen Sie die Programmierkonventionen:
- zwei Leerzeichen, keine Tabs
- keine abschließenden Leerzeichen, leere Zeilen sollten keine Leerzeichen enthalten
- verwenden Sie Leerzeichen um Operatoren, nach Kommas, Doppelpunkten, Semikolons, um
{und vor} - kein Leerzeichen nach
(,[oder vor],) - verwenden Sie die Ruby 1.9 Hash-Syntax: bevorzugen Sie
{ a: 1 }gegenüber{ :a => 1 } - bevorzugen Sie
class << self; def method; endgegenüberdef self.methodfür Klassenmethoden - bevorzugen Sie
{ ... }gegenüberdo ... endfür einzeilige Blöcke, vermeiden Sie die Verwendung von{ ... }für mehrzeilige Blöcke - vermeiden Sie
return, wenn es nicht erforderlich ist
-
Commit:
git commit -m "Eine kurze Zusammenfassung der Änderung" -m "Eine detaillierte Beschreibung der Änderung"Lassen Sie eine Commit-Nachricht niemals leer – dies ist ein hilfreicher Leitfaden zum Verfassen von Commit-Nachrichten. Die Nachricht sollte mit einer kurzen (maximal 72 Zeichen) Zusammenfassung in der ersten Zeile beginnen, gefolgt von einer Leerzeile und dann einer detaillierteren Beschreibung der Änderung. Sie können bei Bedarf Markdown-Syntax für einfache Formatierungen verwenden.
Stellen Sie sicher, dass die Commit-Titel gemäß den Discourse-Konventionen präfixiert sind.
5 (a). Linting:
JavaScript-Code wird mit eslint und formatiert mit prettier gelintet. Ruby wird mit RuboCop und formatiert mit Syntax Tree gelintet. SCSS/CSS wird mit stylelint gelintet. Ember-Vorlagen werden mit ember-template-lint gelintet. Alle diese Prüfungen werden automatisch in GitHub Actions ausgeführt, wann immer Sie einen Pull Request für Discourse erstellen.- Es wird dringend empfohlen, unsere Pre-Commit-Git-Hooks mit
lefthookzu installieren. Dies wird bei jedem Commit im Discourse-Kern automatisch ausgeführt und meldet Probleme mit den verschiedenen Sprachen und Vorlagen, bevor Sie sie pushen und warten müssen, bis die GitHub CI ausgeführt wird. Führen Sie dies in Ihrem Projektstammverzeichnis aus:pnpm lefthook install
- Es wird dringend empfohlen, unsere Pre-Commit-Git-Hooks mit
-
Branch aktualisieren:
git fetch origin git rebase origin/main -
Fork:
git remote add mine git@github.com:<your-username>/discourse.git -
Auf Ihren Remote-Speicherort pushen:
git push mine new_discourse_branch -
Einen Pull Request erstellen:
- Navigieren Sie zu Ihrem Repository auf GitHub.
- Klicken Sie auf „Pull Request“.
- Geben Sie Ihren Branch-Namen im Feld „branch“ ein.
- Klicken Sie auf „Commit Range aktualisieren“.
- Überprüfen Sie die Änderungen in den Registerkarten „Commits“ und „Geänderte Dateien“.
- Geben Sie einen Titel und eine Beschreibung ein.
- Klicken Sie auf „Pull Request senden“.
Bereinigen Sie vor dem Senden eines Pull-Requests die Historie, gehen Sie Ihre Commits durch und führen Sie kleinere Änderungen und Korrekturen in den entsprechenden Commits zusammen. Sie können Commits mit dem interaktiven Rebase-Befehl zusammenfassen:
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
# Der Editor öffnet sich und ermöglicht es Ihnen, die Commit-Historie zu ändern
# Befolgen Sie die Anweisungen am unteren Rand des Editors
git push -f mine new_discourse_branch
- Auf Feedback reagieren:
- Reagieren Sie auf Feedback und seien Sie bereit, vorgeschlagene Änderungen umzusetzen.
- Denken Sie daran, dass Feedback bedeutet, dass Ihre Arbeit geschätzt wird und zur Aufnahme vorgesehen ist.
Vielen Dank für Ihren Beitrag zum Open-Source-Projekt Discourse!