Beitrag zur Entwicklung von Discourse

[Discourse]

Dieser Leitfaden richtet sich an alle, die zum Open-Source-Projekt Discourse beitragen möchten. Er erläutert die Einrichtung und Konventionen, die für eine effektive Zusammenarbeit notwendig sind.

Erforderliches Benutzerlevel: Jeder kann Code beitragen, jedoch solltest du mit Ruby und JavaScript vertraut sein.

Zusammenfassung

Diese Dokumentation behandelt Folgendes:

• Einrichten deiner Entwicklungsumgebung
• Verstehen, wo du mit dem Beitrag beginnen solltest
• Erstellen und Arbeiten mit Discourse-Plugins
• Beitrag zum Discourse-Kerncode
• Zu befolgende Code-Konventionen
• Einreichen deiner Beiträge auf GitHub

Einrichten der Entwicklungsumgebung

Bevor du mit dem Beitrag beginnst, stelle sicher, dass deine Entwicklungsumgebung ordnungsgemäß eingerichtet ist. Folge der entsprechenden Anleitung für deine Plattform:

• Alle Plattformen: Discourse für die Entwicklung mit Docker installieren
• Mac OS X: Anfängerleitfaden zur Installation von Discourse unter macOS für die Entwicklung
• Linux (Ubuntu): Anfängerleitfaden zur Installation von Discourse unter Ubuntu für die Entwicklung
• Windows: Anfängerleitfaden zur Installation von Discourse unter Windows 10 für die Entwicklung

Den Einstieg finden

Discourse ist ein großes Projekt, und das Verständnis der zugrunde liegenden Technologien wie Ruby und JavaScript ist unerlässlich. Für Hinweise zum Einstieg sieh dir den Anfängerleitfaden an.

Erstellen und Arbeiten mit Plugins

Plugins bieten eine Möglichkeit, die Interna von Discourse in handhabbaren Teilen zu verstehen und ermöglichen es dir, einfach mit dem Beitrag von Code zu beginnen. Beginne mit:

• Developing Discourse Plugins - Part 1 - Create a basic plugin
• (deprecated) Plugin outlet locations theme component

Für Inspiration erkunde beliebte Ideen in Contribute > Feature und Customization > Extras.

Beitrag zum Discourse-Kerncode

Der Kerncode von Discourse wird im Core-Repository auf GitHub verwaltet.

Unterzeichnung der CLA

Bevor du beiträgst, lies und unterzeichne das Electronic Discourse Forums Contribution License Agreement. Das Team kann Pull Requests (PRs) von Nutzern, die die CLA nicht unterzeichnet haben, rechtlich nicht annehmen.

Aufwärmen mit Einstiegsaufgaben

Erkunde das Tag pr-welcome für gute Aufgaben zum Einstieg.

Durcharbeiten der Fehlerliste

Behebe Fehler aus der Liste der offenen Fehler, sortiert nach Likes. Hinterlasse eine Notiz, wenn du an einem Fehler arbeitest – falls du ihn nicht abschließt, hinterlasse alle relevanten Notizen, damit jemand anderes deine Arbeit fortsetzen kann.

Hilfe bei Feature-Themen

Trage Details und Mockups zu Feature-Anfragen bei, um ihren Genehmigungsprozess zu unterstützen. Denke daran, dass nicht jedes Feature in den Kerncode aufgenommen wird.

Verbesserung der Leistung

Wir freuen uns über Pull Requests, die die Client- oder Serverseitige Leistung verbessern, mit Fokus auf hochwirksame Bereiche wie das initiale Laden der Startseite oder der Themenansicht.

Verbesserung von Discourse-gewarteten Projekten

Trage zu anderen Open-Source-Projekten bei, die von Discourse gewartet werden. Zu den bemerkenswerten Projekten gehören:

• Logster - Web-GUI-Logviewer
• Message Bus - Engine für Live-Site-Interaktionen
• Rack Mini Profiler - Diagnose-Tool
• Discourse API - API-Consumer
• Discourse Docker - Discourse-Verteilungs-Engine
• WP Discourse - WordPress-Plugin
• Memory Profiler - Profiler für Ruby
• Ember Performance - Ember-Performance-Test-Suite

Code-Konventionen

Namensgebung ist KRITISCH

Strebe eine 100%ige Übereinstimmung zwischen den auf der Site verwendeten Begriffen und den Namen von Klassen und Datenbankspalten an (z. B. „posts“).

Kompatibilität mit den neuesten Versionen der Abhängigkeiten ist KRITISCH

Stelle die Kompatibilität mit den neuesten stabilen Releases von Bibliotheken wie Rails, Ruby und Ember sicher. Teste auf Regressionen bei der Aktualisierung von Abhängigkeiten.

Nur-Test-Beiträge sind willkommen

Test-Beiträge sind willkommen, insbesondere für ungetestete Prozesse und Controller-Aktionen. Vermeide Mocking, es sei denn, es ist absolut notwendig.

Nur-Refactoring-Beiträge sind NICHT willkommen

Vermeide das Einreichen von Pull Requests, die nur Refactoring enthalten. Behebe stattdessen einen Fehler oder implementiere ein Feature, während du den Code verbesserst.

Einreichen von Code auf GitHub

Schritt-für-Schritt-Arbeitsablauf

1. Klone das Discourse-Repository:

   git clone https://github.com/discourse/discourse.git
   

2. Erstelle einen neuen Branch:

   cd discourse
   git checkout -b new_discourse_branch
   

3. Codieren:

   • Halte dich an die vorhandenen Code-Konventionen, die du im Code findest.
   • Füge Tests hinzu und stelle sicher, dass sie bestanden werden.
   • Verweise auf relevante Diskussionen im Discourse-Meta-Forum.

4. Befolge die Code-Konventionen:

   • zwei Leerzeichen, keine Tabs
   • keine nachgestellten Leerzeichen, leere Zeilen sollten keine Leerzeichen enthalten
   • Leerzeichen um Operatoren, nach Kommas, Doppelpunkten, Semikolons, um { und vor } verwenden
   • kein Leerzeichen nach (, [ oder vor ], )
   • Ruby 1.9 Hash-Syntax verwenden: { a: 1 } bevorzugen gegenüber { :a => 1 }
   • class << self; def method; end für Klassenmethoden bevorzugen gegenüber def self.method
   • { ... } für einzeilige Blöcke bevorzugen, do ... end vermeiden; { ... } für mehrzeilige Blöcke vermeiden
   • return vermeiden, wenn nicht erforderlich

5. Commit:

   git commit -m "Eine kurze Zusammenfassung der Änderung" -m "Eine detaillierte Beschreibung der Änderung"
   

   Hinterlasse niemals eine leere Commit-Nachricht – dies ist ein hilfreicher Leitfaden zum Schreiben von Commit-Nachrichten. Die Nachricht sollte mit einer kurzen (max. 72 Zeichen) Zusammenfassung in der ersten Zeile beginnen, gefolgt von einer Leerzeile und dann einer detaillierteren Beschreibung der Änderung. Du kannst Markdown-Syntax für einfaches Styling verwenden, wenn nötig.

   Stelle sicher, dass du Commit-Titel gemäß den Discourse-Konventionen prefixst.

   5 (a). Linting:
   JavaScript-Code wird mit eslint gelintet und mit prettier formatiert. Ruby wird mit RuboCop gelintet und mit Syntax Tree formatiert. SCSS/CSS wird mit stylelint gelintet. Ember-Vorlagen werden mit ember-template-lint gelintet.所有这些检查都会在 GitHub Actions 中自动运行，只要为 Discourse 创建 pull request。

   • Es wird dringend empfohlen, unsere pre-commit Git-Hooks mit lefthook zu installieren. Dies wird automatisch jedes Mal ausgeführt, wenn du einen Commit im Discourse-Kern machst, und Probleme mit den verschiedenen Sprachen und Vorlagen melden, bevor du sie pushst und auf den GitHub CI warten musst. Führe dies im Stammverzeichnis deines Projekts aus:

     pnpm lefthook install
     

6. Aktualisiere deinen Branch:

   git fetch origin
   git rebase origin/main
   

7. Fork:

   git remote add mine git@github.com:<your-username>/discourse.git
   

8. Push zu deinem Remote:

   git push mine new_discourse_branch
   

9. Stelle eine Pull Request ein:

   • Navigiere zu deinem Repository auf GitHub.
   • Klicke auf „Pull Request“.
   • Schreibe deinen Branch-Namen in das Branch-Feld.
   • Klicke auf „Update Commit Range“.
   • Überprüfe die Änderungen in den Tabs „Commits“ und „Files Changed“.
   • Gib einen Titel und eine Beschreibung an.
   • Klicke auf „Send pull request“.

   Vor dem Einreichen einer Pull-Request bereinige die Historie, gehe deine Commits durch und squashe kleinere Änderungen und Korrekturen in die entsprechenden Commits zusammen. Du kannst Commits mit dem interaktiven Rebase-Befehl squaschen:

git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i

< der Editor öffnet sich und ermöglicht dir, die Commit-Historie zu ändern >
< folge den Anweisungen am unteren Rand des Editors >

git push -f mine new_discourse_branch

10. Reagiere auf Feedback:
    • Sei reaktiv auf Feedback und bereit, vorgeschlagene Änderungen umzusetzen.
    • Denke daran, dass Feedback bedeutet, dass deine Arbeit wertgeschätzt wird und für die Aufnahme vorgesehen ist.

Vielen Dank, dass du zum Open-Source-Projekt Discourse beigetragen hast!