Contribuire allo sviluppo di Discourse

[Discourse]

Questa guida è pensata per coloro che desiderano contribuire al progetto open source di Discourse, illustrando la configurazione e le convenzioni necessarie per una collaborazione efficace.

Livello utente richiesto: Sebbene chiunque possa contribuire con codice, è necessario avere familiarità con Ruby e JavaScript.

Sommario

Questa documentazione tratterà i seguenti argomenti:

• Configurazione dell’ambiente di sviluppo
• Capire da dove iniziare a contribuire
• Creazione e lavoro con i plugin di Discourse
• Contribuire al core di Discourse
• Convenzioni di codifica da seguire
• Invio dei 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 usando Docker
• Mac OS X: Guida per principianti all’installazione di Discourse su macOS per lo Sviluppo
• Linux (Ubuntu): Guida per principianti all’installazione di Discourse su Ubuntu per lo Sviluppo
• Windows: Guida per principianti all’installazione di Discourse su Windows 10 per lo Sviluppo

Sapere da dove iniziare

Discourse è un progetto vasto, ed è essenziale comprenderne le tecnologie sottostanti come Ruby e JavaScript. Per una guida su come iniziare, fai riferimento alla guida per principianti.

Creazione e lavoro con i plugin

I plugin offrono un modo per comprendere gli interni di Discourse in porzioni gestibili e ti permettono di iniziare a contribuire con codice facilmente. Inizia da:

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

Per ispirazione, esplora idee popolari in #feature e #plugin:extras.

Contribuire al core di Discourse

Il codice sorgente di Discourse è gestito in repository core su GitHub.

Firma della CLA

Prima di contribuire, leggi e firma il Accordo di Licenza per i Contributi dei Forum Elettronici di Discourse. Il team non può legalmente accettare pull request (PR) da utenti che non hanno firmato la CLA.

Riscaldarsi con i task di avviamento

Esplora il tag pr-welcome per buoni task con cui iniziare.

Lavorare sulla lista dei bug

Correggi i bug dalla lista dei bug aperti ordinati per “Mi piace”. Lascia una nota se stai lavorando su un bug; se non lo completi, lascia tutte le note pertinenti affinché qualcun altro possa continuare il tuo lavoro.

Aiutare con gli argomenti sulle funzionalità

Contribuisci con dettagli e mockup alle richieste di funzionalità per aiutarne il processo di approvazione. Ricorda, non tutte le funzionalità saranno incluse nel core.

Migliorare le prestazioni

Accogliamo con favore le pull request che migliorano le prestazioni lato client o server, concentrandosi su aree ad alto impatto come il caricamento iniziale della prima pagina o della vista degli argomenti.

Migliorare i progetti mantenuti da Discourse

Contribuisci ad altri progetti open source mantenuti da Discourse. Alcuni progetti degni di nota includono:

• Logster - visualizzatore di log GUI web
• Message Bus - motore per interazioni del sito in tempo reale
• 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 Ember

Convenzioni di codifica

La denominazione è CRITICA

Punta al 100% di parità tra i termini usati sul sito e i nomi di classi e colonne nel database (es. “posts”).

La compatibilità con le ultime versioni delle dipendenze è CRITICA

Assicurati della compatibilità con le ultime versioni stabili di librerie come Rails, Ruby ed Ember. Testa le regressioni quando aggiorni le dipendenze.

I contributi solo di test sono benvenuti

I contributi di test sono benvenuti, specialmente per processi e azioni del controller non testati. Evita il mocking a meno che non sia assolutamente necessario.

I contributi di solo refactoring NON sono benvenuti

Evita di inviare pull request di solo refactoring. Invece, correggi un bug o implementa una funzionalità migliorando il codice.

Invio del codice su GitHub

Flusso di lavoro passo passo

1. Clona il repository Discourse:

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

2. Crea un nuovo branch:

   cd discourse
   git checkout -b nuovo_branch_discourse
   

3. Codifica:

   • Aderisci alle convenzioni di codice esistenti che trovi nel codice.
   • Includi i test e assicurati che passino.
   • Fai riferimento alle discussioni pertinenti sul forum meta di Discourse.

4. Segui le convenzioni di codifica:

   • due spazi, nessun tabulatore
   • nessun whitespace finale, le righe vuote non devono contenere spazi
   • usa spazi attorno agli operatori, dopo le virgole, i due punti, i punti e virgola, attorno a { e prima di }
   • nessuno spazio dopo (, [ o prima di ], )
   • usa la sintassi hash di Ruby 1.9: preferisci { a: 1 } a { :a => 1 }
   • preferisci class << self; def method; end a def self.method per i metodi di classe
   • preferisci { ... } a do ... end per i blocchi su una singola riga, evita di usare { ... } per i blocchi su più righe
   • evita return quando non necessario

5. Commit:

   git commit -m "Un breve riassunto della modifica" -m "Una descrizione dettagliata della modifica"
   

   Non lasciare mai un messaggio di commit vuoto - questa è una guida utile per scrivere messaggi di commit. Il messaggio dovrebbe iniziare con un breve riassunto (massimo 72 caratteri) nella prima riga, seguito da una riga vuota, e poi una descrizione più dettagliata della modifica. Puoi usare la sintassi markdown per semplici stili se necessario.

   Assicurati di anteporre ai titoli dei commit secondo le convenzioni di Discourse.

   5 (a). Linting (Controllo di qualità del codice):
   Il codice JavaScript viene sottoposto a linting con eslint e formattato con prettier. Ruby viene sottoposto a linting con RuboCop e formattato con Syntax Tree. SCSS/CSS viene sottoposto a linting con stylelint. I template Ember vengono sottoposti a linting con ember-template-lint. Tutti questi controlli vengono eseguiti automaticamente nelle azioni di GitHub ogni volta che crei una pull request per Discourse.

   • È fortemente consigliato installare i nostri ganci git pre-commit usando lefthook. Questo verrà eseguito automaticamente ogni volta che effettui un commit nel core di Discourse, e solleverà problemi con i vari linguaggi e template prima che tu li carichi e debba aspettare che CI di GitHub venga eseguito. Esegui questo nella root del tuo progetto:

     pnpm lefthook install
     

6. Aggiorna il tuo branch:

   git fetch origin
   git rebase origin/main
   

7. Fork:

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

8. Esegui il push sul tuo remote:

   git push mine nuovo_branch_discourse
   

9. Emetti una pull request:

   • Naviga al tuo repository su GitHub.
   • Clicca su “Pull Request”.
   • Scrivi il nome del tuo branch nel campo del 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, esamina i tuoi commit e unisci le modifiche minori e le correzioni nei commit corrispondenti. Puoi unire i commit con il comando rebase interattivo:

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

# L'editor si apre e ti permette di modificare la cronologia dei commit 
# Segui le istruzioni in fondo all'editor

git push -f mine nuovo_branch_discourse

10. Rispondi ai feedback:
    • Sii reattivo ai feedback e pronto a implementare le modifiche suggerite.
    • Ricorda, ricevere feedback significa che il tuo lavoro è apprezzato e destinato all’inclusione.

Grazie per aver contribuito al progetto open source di Discourse!