Contributing to Discourse development

Documentazione Contribuire
1

:bookmark: 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.

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

Sommario

Questa documentazione coprirà 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:

Sapere da dove iniziare

Discourse è un progetto vasto, ed è essenziale comprenderne le tecnologie sottostanti come Ruby e JavaScript. Per una guida su come iniziare, consulta la 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 con:

Per ispirazione, esplora le idee popolari in Feature e Plugin > Extras.

Contribuire al core di Discourse

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

Firma del CLA

Prima di contribuire, leggi e firma il Contributory License Agreement (CLA) di Electronic Discourse Forums. Il team non può accettare legalmente le pull request (PR) dagli utenti che non hanno firmato il CLA.

Riscaldamento con attività per principianti

Esplora il tag pr-welcome per buone attività con cui iniziare.

Lavorare attraverso la 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 le discussioni 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 homepage o della vista argomento.

Migliorare i progetti mantenuti da Discourse

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

Convenzioni di codifica

La denominazione è FONDAMENTALE

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

La compatibilità con le ultime versioni delle dipendenze è FONDAMENTALE

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

I contributi di solo 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 di codice su GitHub

Flusso di lavoro passo dopo passo

  1. Clona il repository di Discourse:

    git clone git@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, niente tabulazioni
    • niente spazi bianchi finali, le righe vuote non devono avere spazi
    • usa spazi attorno agli operatori, dopo le virgole, i due punti, i punti e virgola, attorno a { e prima di }
    • niente 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 singola riga, evita di usare { ... } per i blocchi su più righe
    • evita return quando non è richiesto

  5. Commit:

    git commit -m "Un breve riepilogo 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 riepilogo (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 una semplice formattazione se necessario.

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

    5 (a). Linting:
    Il codice JavaScript viene sottoposto a linting con eslint e le condizioni di formattazione con prettier. Ruby viene sottoposto a linting con RuboCop. Tutti questi controlli vengono eseguiti automaticamente nelle azioni di GitHub ogni volta che crei una pull request per Discourse.

    • È fortemente consigliato installare i nostri hook git pre-commit usando lefthook. Questo verrà eseguito automaticamente ogni volta che esegui 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:
      mkdir .git/hooks
npx lefthook install

  6. Aggiorna il tuo branch:

    git fetch origin
git rebase origin/main

  7. Fork:

    git remote add mine git@github.com:<your-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 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
  1. Rispondi al feedback:
    • Sii reattivo al feedback e pronto a implementare le modifiche suggerite.
    • Ricorda, il feedback significa che il tuo lavoro è apprezzato e destinato all’inclusione.

Grazie per aver contribuito al progetto open-source di Discourse!

73 Mi Piace