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 del 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 di Discourse (Discourse core)
- Convenzioni di codifica da seguire
- Invio 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: Installa Discourse per lo sviluppo usando 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 di grandi dimensioni 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 le parti interne di Discourse in porzioni 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 Customization > Extras.
Contributo al nucleo di Discourse (Discourse core)
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 Elettronici Discourse. Il team non può accettare legalmente le pull request (PR) da utenti che non hanno firmato il CLA.
Riscaldarsi con compiti iniziali
Esplora il tag pr-welcome per trovare buoni compiti con cui iniziare.
Affrontare la lista dei bug
Correggi i bug presenti nella lista dei bug aperti ordinata per like. Lascia un commento se stai lavorando a un bug; se non riesci a completarlo, lascia eventuali note rilevanti affinché qualcun altro possa continuare il tuo lavoro.
Aiutare con gli argomenti sulle funzionalità
Contribuisci con dettagli e mockup alle richieste di funzionalità per facilitare il processo di approvazione. Ricorda che non tutte le funzionalità verranno incluse nel nucleo.
Migliorare 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 homepage o la visualizzazione degli argomenti.
Migliorare 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 dell’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 le regressioni quando aggiorni le dipendenze.
I contributi solo per i test sono benvenuti
I contributi relativi ai test sono benvenuti, in particolare per processi e azioni dei controller non ancora testati. Evita di usare il mocking a meno che non sia assolutamente necessario.
I contributi solo di refactoring NON sono benvenuti
Evita di inviare pull request contenenti solo refactoring. Invece, correggi un bug o implementa una funzionalità migliorando nel contempo il codice.
Invio 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 intorno agli operatori, dopo le virgole, due punti, punti e virgola, intorno 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 "Breve riassunto della modifica" -m "Descrizione dettagliata della modifica"Non lasciare mai vuoto il messaggio del commit - questa è una guida utile per scrivere i messaggi dei commit. Il messaggio dovrebbe iniziare con un riassunto breve (massimo 72 caratteri) sulla prima riga, seguito da una riga vuota e poi da una descrizione più dettagliata della modifica. Puoi usare la sintassi markdown per uno stile semplice se necessario.
Assicurati di prefissare 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 di 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 usando
lefthook. Questo verrà eseguito automaticamente ogni volta che fai un commit nel nucleo di Discourse e segnalerà problemi con i vari linguaggi e template prima di caricarli e dover aspettare che la CI di GitHub venga eseguita. Esegui questo nella root del tuo progetto:pnpm lefthook install
- Si consiglia vivamente di installare i nostri hook git pre-commit usando
-
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 -
Emetti 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 inviare una pull request, pulisci la cronologia, rivedi i tuoi commit e accorpa le modifiche minori e le correzioni nei commit corrispondenti. Puoi accorpare 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 all’inclusione.
Grazie per aver contribuito al progetto open source Discourse!