Questa guida è pensata per chi desidera contribuire al progetto open source Discourse, dettagliando la configurazione e le convenzioni necessarie per una collaborazione efficace.
Livello utente richiesto: Sebbene chiunque possa contribuire con il codice, è necessario avere familiarità con Ruby e JavaScript.
Riepilogo
Questa documentazione coprirà i seguenti argomenti:
- Configurazione dell’ambiente di sviluppo
- Comprensione di dove iniziare a contribuire
- Creazione e utilizzo dei plugin di Discourse
- Contributo al nucleo (core) di Discourse
- Convenzioni di codifica da seguire
- Sottomissione dei propri contributi su GitHub
Configurazione dell’ambiente di sviluppo
Prima di iniziare a contribuire, assicurati che il tuo ambiente di sviluppo sia configurato correttamente. Segui la guida appropriata per la tua piattaforma:
- Tutte le piattaforme: Installare Discourse per lo sviluppo utilizzando Docker
- Mac OS X: Guida per principianti per installare Discourse su macOS per lo sviluppo
- Linux (Ubuntu): Guida per principianti per installare Discourse su Ubuntu per lo sviluppo
- Windows: Guida per principianti per installare Discourse su Windows 10 per lo sviluppo
Sapere da dove iniziare
Discourse è un progetto ampio e comprendere le sue tecnologie sottostanti, come Ruby e JavaScript, è essenziale. Per indicazioni su come iniziare, consulta la guida per principianti.
Creazione e utilizzo dei plugin
I plugin offrono un modo per comprendere gli interni di Discourse in parti gestibili e ti permettono di iniziare a contribuire con il codice facilmente. Inizia con:
- Developing Discourse Plugins - Part 1 - Create a basic plugin
- (deprecated) Plugin outlet locations theme component
Per ispirazione, esplora le idee popolari nei canali Contribute > Feature e #plugin:extras.
Contributo al nucleo (core) di Discourse
Il codice del nucleo di Discourse è gestito nel repository principale su GitHub.
Firma del CLA
Prima di contribuire, leggi e firma l’Accordo di Licenza di Contribuzione per i Forum Discourse Elettronici. Il team non può accettare legalmente le pull request (PR) da utenti che non hanno firmato il CLA.
Riscaldarsi con attività per principianti
Esplora il tag pr-welcome per trovare buone attività con cui iniziare.
Affronta l’elenco dei bug
Correggi i bug presenti nell’elenco dei bug aperti ordinati per like. Lascia una nota se stai lavorando a un bug: se non lo completi, lascia eventuali note rilevanti affinché qualcun altro possa continuare il tuo lavoro.
Aiuta con gli argomenti sulle funzionalità
Contribuisci con dettagli e mockup alle richieste di funzionalità per agevolare il processo di approvazione. Ricorda che non tutte le funzionalità saranno incluse nel nucleo.
Migliora le prestazioni
Accogliamo con favore le pull request che migliorano le prestazioni lato client o lato server, concentrandoci su aree ad alto impatto come il caricamento iniziale della home page o la visualizzazione degli argomenti.
Migliora i progetti mantenuti da Discourse
Contribuisci ad altri progetti open source mantenuti da Discourse. Alcuni progetti notevoli includono:
- Logster - visualizzatore di log GUI web
- Message Bus - motore per le interazioni in tempo reale sul sito
- Rack Mini Profiler - strumento di diagnostica
- Discourse API - consumer API
- Discourse Docker - motore di distribuzione di Discourse
- WP Discourse - plugin per WordPress
- Memory Profiler - profiler per Ruby
- Ember Performance - suite di test delle prestazioni per Ember
Convenzioni di codifica
La denominazione è CRITICA
Punta a una parità del 100% tra i termini utilizzati sul sito e i nomi delle classi e delle colonne nel database (ad esempio, “posts”).
La compatibilità con le ultime versioni delle dipendenze è CRITICA
Assicurati la compatibilità con le ultime versioni stabili di librerie come Rails, Ruby ed Ember. Esegui test per rilevare regressioni durante l’aggiornamento delle dipendenze.
Sono benvenuti i contributi solo per i test
I contributi relativi ai test sono benvenuti, in particolare per processi e azioni dei controller non testati. Evita di utilizzare il mocking a meno che non sia assolutamente necessario.
I contributi solo per il refactoring NON sono benvenuti
Evita di inviare pull request contenenti solo refactoring. Invece, correggi un bug o implementa una funzionalità migliorando il codice nel processo.
Sottomissione del codice su GitHub
Flusso di lavoro passo dopo passo
-
Clona il repository di Discourse:
git clone https://github.com/discourse/discourse.git -
Crea un nuovo branch:
cd discourse git checkout -b new_discourse_branch -
Codifica:
- Attieniti alle convenzioni di codifica esistenti che trovi nel codice.
- Includi i test e assicurati che passino.
- Riferisciti alle discussioni rilevanti sul forum meta di Discourse.
-
Segui le convenzioni di codifica:
- due spazi, nessun tab
- nessun spazio bianco finale, le righe vuote non devono contenere spazi
- usa spazi attorno agli operatori, dopo le virgole, due punti, punti e virgola, attorno a
{e prima di} - nessun spazio dopo
(,[o prima di],) - usa la sintassi hash di Ruby 1.9: preferisci
{ a: 1 }a{ :a => 1 } - preferisci
class << self; def method; endadef self.methodper i metodi di classe - preferisci
{ ... }ado ... endper i blocchi su una singola riga, evita di usare{ ... }per i blocchi su più righe - evita
returnquando non è necessario
-
Commit:
git commit -m "Un breve riepilogo della modifica" -m "Una descrizione dettagliata della modifica"Non lasciare mai vuoto il messaggio del commit: questa è una guida utile per scrivere i messaggi dei commit. Il messaggio deve iniziare con un riepilogo breve (massimo 72 caratteri) sulla prima riga, seguito da una riga vuota e poi da una descrizione più dettagliata della modifica. Puoi utilizzare la sintassi markdown per uno stile semplice se necessario.
Assicurati di anteporre i titoli dei commit secondo le convenzioni di Discourse.
5 (a). Linting:
Il codice JavaScript viene controllato con eslint e formattato con prettier. Ruby viene controllato con RuboCop e formattato con Syntax Tree. SCSS/CSS viene controllato con stylelint. I template Ember vengono controllati con ember-template-lint. Tutti questi controlli vengono eseguiti automaticamente nelle GitHub Actions ogni volta che crei una pull request per Discourse.- Si consiglia vivamente di installare i nostri hook git pre-commit utilizzando
lefthook. Questo verrà eseguito automaticamente ogni volta che effettui un commit nel nucleo di Discourse, segnalando problemi con i vari linguaggi e template prima di caricarli e dover aspettare che la CI di GitHub venga eseguita. Esegui questo comando nella root del tuo progetto:pnpm lefthook install
- Si consiglia vivamente di installare i nostri hook git pre-commit utilizzando
-
Aggiorna il tuo branch:
git fetch origin git rebase origin/main -
Fork:
git remote add mine git@github.com:<your-username>/discourse.git -
Carica sul tuo remoto:
git push mine new_discourse_branch -
Invia una pull request:
- Vai al tuo repository su GitHub.
- Clicca su “Pull Request”.
- Scrivi il nome del tuo branch nel campo branch.
- Clicca su “Update Commit Range”.
- Verifica le modifiche nelle schede “Commits” e “Files Changed”.
- Fornisci un titolo e una descrizione.
- Clicca su “Send pull request”.
Prima di sottomettere una pull request, pulisci la cronologia, rivedi i tuoi commit e unisci le modifiche minori e le correzioni nei commit corrispondenti. Puoi unire i commit con il comando di rebase interattivo:
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
< l'editor si apre e ti permette di modificare la cronologia dei commit >
< segui le istruzioni nella parte inferiore dell'editor >
git push -f mine new_discourse_branch
- Rispondi ai feedback:
- Sii ricettivo ai feedback e pronto a implementare le modifiche suggerite.
- Ricorda che il feedback significa che il tuo lavoro è apprezzato e destinato a essere incluso.
Grazie per aver contribuito al progetto open source Discourse!