Beitrag zur Entwicklung von Discourse

[Discourse]

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

Erforderliches Benutzerlevel: Während jeder Code beitragen kann, müssen Sie mit Ruby und JavaScript vertraut sein.

Zusammenfassung

Diese Dokumentation behandelt Folgendes:

• Einrichten Ihrer Entwicklungsumgebung
• Verstehen, wo Sie mit dem Beitrag beginnen sollen
• Erstellen und Arbeiten mit Discourse-Plugins
• Beiträge zum Discourse-Core
• Zu befolgende Codierkonventionen
• Einreichen Ihrer Beiträge auf GitHub

Einrichten der Entwicklungsumgebung

Bevor Sie mit dem Beitrag beginnen, stellen Sie sicher, dass Ihre Entwicklungsumgebung korrekt eingerichtet ist. Folgen Sie der entsprechenden Anleitung für Ihre Plattform:

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

Wissen, wo Sie beginnen sollen

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 lesen Sie den Leitfaden für Neueinsteiger.

Erstellen und Arbeiten mit Plugins

Plugins bieten eine Möglichkeit, die Interna von Discourse in handhabbaren Teilen zu verstehen und es Ihnen zu ermöglichen, leicht mit dem Beitrag von Code zu beginnen. Beginnen Sie mit:

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

Für Inspiration erkunden Sie beliebte Ideen in Contribute > Feature und #plugin:extras.

Beiträge zum Discourse-Core

Der Discourse-Core-Code wird im Core-Repository auf GitHub verwaltet.

Unterzeichnung der CLA

Bevor Sie beitragen, lesen und unterzeichnen Sie das Elektronische Discourse-Forums-Mitwirkungs-Lizenzvereinbarung. Das Team kann Pull Requests (PRs) von Benutzern, die die CLA nicht unterzeichnet haben, rechtlich nicht akzeptieren.

Aufwärmen mit Starter-Aufgaben

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

Durchgehen 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 abschließen, hinterlassen Sie relevante Notizen für jemanden, der Ihre Arbeit fortsetzen kann.

Hilfe bei Feature-Themen

Tragen Sie Details und Mockups zu Feature-Anfragen bei, um deren Genehmigungsprozess zu unterstützen. Denken Sie daran, dass nicht jedes Feature in den Core aufgenommen wird.

Leistung verbessern

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

Discourse-Verwaltete Projekte verbessern

Tragen Sie zu anderen Open-Source-Projekten bei, die von Discourse verwaltet werden. Zu einigen bemerkenswerten Projekten gehören:

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

Codierkonventionen

Benennung ist KRITISCH

Streben Sie nach 100%iger Übereinstimmung zwischen den auf der Website verwendeten Begriffen und den Namen von Klassen und Spalten in der Datenbank (z. B. „posts“).

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

Stellen Sie die Kompatibilität mit den neuesten stabilen Releases von Bibliotheken wie Rails, Ruby und Ember sicher. Testen Sie auf Regressionen beim Aktualisieren von Abhängigkeiten.

Nur-Test-Beiträge sind willkommen

Test-Beiträge sind willkommen, insbesondere für ungetestete 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 Nur-Refactoring-Pull-Requests. Beheben Sie stattdessen einen Fehler oder implementieren Sie ein Feature, während Sie den Code verbessern.

Einreichen von Code auf GitHub

Schritt-für-Schritt-Workflow

1. Klonen Sie das Discourse-Repository:

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

2. Erstellen Sie einen neuen Branch:

   cd discourse
   git checkout -b new_discourse_branch
   

3. Codieren:

   • Halten Sie sich an die bestehenden Codierkonventionen, die Sie im Code finden.
   • Fügen Sie Tests hinzu und stellen Sie sicher, dass sie bestehen.
   • Verweisen Sie auf relevante Diskussionen im Discourse-Meta-Forum.

4. Codierkonventionen befolgen:

   • 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 bevorzugen gegenüber def self.method für Klassenmethoden
   • { ... } bevorzugen gegenüber do ... end für einzeilige Blöcke, { ... } für mehrzeilige Blöcke vermeiden
   • return vermeiden, wenn nicht erforderlich

5. Commit:

   git commit -m "A short summary of the change" -m "A detailed description of the change"
   

   Lassen Sie die Commit-Nachricht niemals leer – dies ist ein hilfreicher Leitfaden zum Schreiben von Commit-Nachrichten. Die Nachricht sollte mit einer kurzen Zusammenfassung (max. 72 Zeichen) in der ersten Zeile beginnen, gefolgt von einer leeren Zeile und dann einer detaillierteren Beschreibung der Änderung. Sie können Markdown-Syntax für einfaches Styling verwenden, wenn nötig.

   Stellen Sie sicher, dass Sie Commit-Titel gemäß den Discourse-Konventionen präfixen.

   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. Alle diese Prüfungen werden automatisch in GitHub-Aktionen ausgeführt, whenever Sie einen Pull Request für Discourse erstellen.

   • Es wird dringend empfohlen, unsere pre-commit git hooks mit lefthook zu installieren. Dies wird automatisch jedes Mal ausgeführt, wenn Sie einen Commit im Discourse-Core machen, und Probleme mit den verschiedenen Sprachen und Vorlagen melden, bevor Sie sie hochladen und auf GitHub CI warten müssen. Führen Sie dies in Ihrem Projektstamm aus:

     pnpm lefthook install
     

6. Aktualisieren Sie Ihren Branch:

   git fetch origin
   git rebase origin/main
   

7. Forken:

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

8. Zum Remote-Repository pushen:

   git push mine new_discourse_branch
   

9. Ein Pull Request erstellen:

   • Navigieren Sie zu Ihrem Repository auf GitHub.
   • Klicken Sie auf „Pull Request“.
   • Geben Sie Ihren Branch-Namen im Branch-Feld ein.
   • Klicken Sie auf „Update Commit Range“.
   • Überprüfen Sie die Änderungen in den Tabs „Commits“ und „Files Changed“.
   • Geben Sie einen Titel und eine Beschreibung an.
   • Klicken Sie auf „Send pull request“.

   Vor dem Einreichen eines Pull-Requests bereinigen Sie die Historie, gehen Sie Ihre Commits durch und squashen kleine Änderungen und Korrekturen in die entsprechenden Commits zusammen. Sie können Commits mit dem interaktiven Rebase-Befehl squashen:

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 >
< folgen Sie den Anweisungen am unteren Rand des Editors >

git push -f mine new_discourse_branch

10. Feedback beantworten:
    • Seien Sie reaktionsfähig auf Feedback und bereit, vorgeschlagene Änderungen umzusetzen.
    • Denken Sie daran, dass Feedback bedeutet, dass Ihre Arbeit wertgeschätzt wird und für die Aufnahme vorgesehen ist.

Vielen Dank, dass Sie zum Discourse Open-Source-Projekt beitragen!