Skip to main content

Contribuire a Flarum

Interessato a contribuire allo sviluppo di Flarum? È fantastico! Dalla segnalazione di un bug alla creazione di richieste particolari: ogni contributo è apprezzato e utile. Flarum non sarebbe qui senza la nostra fenomenale community.

Prima di contribuire, leggi il codice di condotta.

Questo documento è una guida per gli sviluppatori che vogliono contribuire con codice a Flarum. Se hai appena iniziato, ti consigliamo di leggere la documentazione Per iniziare (per ora in inglese) sul funzionamento di Flarum.

Su cosa lavorare

Have Real Impact. There are thousands of Flarum instances, with millions of aggregate end users. By contributing to Flarum, your code will have a positive impact on all of them.

🔮 Shape the Future of Flarum. We have a long backlog, and limited time. If you're willing to champion a feature or change, it's much more likely to happen, and you'll be able to enact your vision for it. Plus, our roadmap and milestones are set by our core development team, and all of us started as contributors. The best road to influence is contributing.

🧑‍💻 Become a Better Engineer. Our codebase is modern, and we heavily value good engineering and clean code. There's also a lot of interesting, challenging problems to solve regarding design, infrastructure, performance, and extensibility. Especially if you're a student or early in your career, working on Flarum is a great opportunity to build development skills.

🎠 It's Fun! We really enjoy working on Flarum: there's a lot of interesting challenges and fun features to build. We also have an active community on our forums and Discord server.

Setup area di sviluppo

Dai un occhiata ai nostri prossimi Traduardi (in inglese) per una panoramica di ciò che deve essere fatto. Consulta le Primi problemi per un elenco di problemi con cui dovrebbe essere relativamente facile iniziare. Se c'è qualcosa di cui non sei sicuro, non esitare a chiedere! Abbiamo tutti cominciato dal principio.

Se hai intenzione di andare avanti e lavorare su qualcosa, commenta il problema pertinente o creane uno nuovo prima. In questo modo possiamo garantire che il tuo prezioso lavoro non sia vano.

Dal momento che Flarum è così estendibile, consigliamo vivamente i nostri documenti per le estensioni come riferimento quando si lavora sul core, così come per le estensioni in bundle. Si dovrebbe iniziare con l'introduzione per una migliore comprensione della nostra filosofia di estensibilità.

Flusso di lavoro nello sviluppo

Impostare un codice locale

flarum/flarum è lo "scheletro" dell'applicazione che usa Composer per scaricare flarum/core e tantissime estensioni. Per lavorare su questi, consigliamo di eseguirne il fork e di clonarli in una Repository di Composer:

git clone https://github.com/flarum/flarum.git
cd flarum

# Set up a Composer path repository for Flarum packages
composer config repositories.0 path "packages/*"
git clone https://github.com/<username>/core.git packages/core
git clone https://github.com/<username>/tags.git packages/tags # etc

Un esempio tipico di flusso di lavoro può essere questo:

Infine, lancia composer install per completare l'installazione dal percorso della repository.

Fatto ciò la tua installazione locale è impostata, assicurati di abilitare la modalità debug in config.php, e imposta display_errors su On nella tua configurazione php. Questo ti permetterà di vedere i dettagli dell'errore sia per Flarum che per PHP. La modalità di debug impone anche una ricompilazione dei file delle risorse di Flarum su ogni richiesta, eliminando la necessità di chiamare php flarum cache:clear dopo ogni modifica al javascript o CSS dell'estensione.

Il codice front-end di Flarum è scritto in ES6 e trasferito in JavaScript. Durante lo sviluppo sarà necessario ricompilare JavaScript utilizzando Node.js. Non creare commit che includono la cartella dist quando crei Pull Request, i file vengono generati in automatico quando viene fatto il merge delle modifiche nel branch master.

cd packages/core/js
npm install
npm run dev

Il processo è lo stesso per le estensioni.

cd packages/tags/js
npm install
npm link ../../core/js
npm run dev

Strumenti di sviluppo

Dopo aver effettuato un fork e clonato la repository su cui lavorerai, dovrai impostare l'hosting locale in modo da poter testare le modifiche. Flarum attualmente non viene fornito con un server di sviluppo, quindi dovrai impostare Apache/NGINX/Caddy/etc per installare Flarum in locale.

Le Tabelle dovrebbero chiamarsi in questo modo:

Le classi CSS di Flarum seguono più o meno il SUIT CSS naming conventions con il formato .ComponentName-descendentName--modifierName.

Stile del codice

Utilizziamo formati chiave standard per denominare le chiavi di traduzione in modo descrittivo e coerente.

  1. 🌳 Crea un branch per le funzionalità partendo da un branch appropriato.

      • Le correzioni di bug* dovrebbero essere inviate all'ultimo branch stabile.
    • Funzionalità minori che sono completamente retrocompatibili con l'attuale versione di Flarum possono essere inviate all'ultimo branch stabile.
  2. 🔨 Scrivi un po' di codice.

    • Vedi sotto per lo stile del codice.
    • Funzionalità minori che sono completamente retrocompatibili con l'attuale versione di Flarum possono essere inviate all'ultimo branch stabile.
    • Funzionalità importanti devono essere sempre inviate al branch master che contiene la successiva versione di Flarum.
    • Internamente usiamo lo schema di denominazione <iniziali>/<breve-descrizione> (es. tz/refactor-frontend).
  3. 🚦 Testa il tuo codice.

    • Aggiungi unit test in base alle esigenze durante la correzione di bug o l'aggiunta di funzionalità.
  4. 💾 Crea dei commit per il tuo codice con un messaggio descrittivo.

    • Se la modifica risolve un problema esistente (di solito, dovrebbe) includere "Fixes #123" in una nuova riga, dove 123 è il numero dell'issue GitHub.
    • Scrivi un buon messaggio accompagnatorio.
    • Vedi qui per maggiori informazioni sui test in Flarum.
  5. 🎁 Invia una Pull Request su GitHub.

    • Riempi i campi della richiesta.
    • Follow the Conventional Commits specification.
    • Fix commits should describe the issue fixed, not how it was fixed.
  6. 🤝 Coinvolgi il team di Flarum per l'approvazione.

    • Riempi i campi della richiesta (pull request).
    • Quando lasci un feedback, aggiungi commenti invece di sovrascriverli o eliminarli (li uniremo noi).
    • NON eseguire il check-in di JavaScript nei file dist Verra fatto automaticamente una volta uniti. Verrà compilato tutto automaticamente durante la fusione.
  7. 🕺 Festeggia per aver contribuito a Flarum!

    • I membri del team esamineranno il tuo codice. Potremmo suggerire alcune modifiche o miglioramenti o alternative, ma per piccoli cambiamenti la tua richiesta pull dovrebbe essere accettata rapidamente.
    • Quando lasci un feedback, aggiungi commenti invece di sovrascriverli o eliminarli (li uniremo noi).
  8. 🕺 Festeggia per aver contribuito a Flarum.

Strumenti di sviluppo

Al fine di mantenere la base di codice Flarum pulita e coerente, abbiamo una serie di linee guida sullo stile di codifica che seguiamo. In caso di dubbio, leggi il codice sorgente.

Non preoccuparti se lo stile del tuo codice non è perfetto! StyleCI unirà automaticamente tutte le correzioni di stile nei repository Flarum dopo il merge delle pull request. Questo ci permette di concentrarci sul contenuto del contributo e non sullo stile del codice.

PHP

Flarum segue gli standard di codice PSR-2 e PSR-4. Inoltre, ci conformiamo a una serie di altre regole di stile. Usiamo il type hinting di PHP 7 dove possibile, e PHPDoc per la documentazione inline. Prova a rispettare lo stile utilizzato dal resto del codice nei tuoi contributi.

  • Gli spazi dei nomi dovrebbero essere in singolare (es. Flarum\Discussion, non Flarum\Discussions)
  • Le interfacce dovrebbero avere il suffisso Interface (es. MailableInterface)
  • Le classi astratte dovrebbero essere precedute da Abstract (es. AbstractModel)
  • I tratti dovrebbero essere suffissi con Trait (es. ScopeVisibilityTrait)

JavaScript

JavaScript di Flarum segue principalmente la Airbnb Style Guide. Utilizziamo ESDoc per fornire documentazione conforme.

Database

Le colonne dovrebbero essere denominate in base al tipo di dati:

  • DATETIME o TIMESTAMP: {verbed}_at (es. created_at, read_at) o {verbed}_until (eg. suspended_until)
  • INT considerato come conteggio: {noun}_count (es. comment_count, word_count)
  • Chiave esterna: {verbed}_{entity}_id (es. hidden_user_id)
    • Il verbo può essere omesso per la relazione primaria (es. autore del post � semplicemente user_id)
  • BOOL: is_{adjective} (es. is_locked)

La Fondazione Flarum riconosce che, ad eccezione di quanto esplicitamente descritto nel presente Accordo, qualsiasi Contributo fornito è "COSÌ COM'È", SENZA GARANZIE O CONDIZIONI DI ALCUN TIPO, ESPLICITE O IMPLICITE, INCLUSE, SENZA LIMITAZIONE, ALCUNA GARANZIA O CONDIZIONE DI TITOLO, NON VIOLAZIONE, COMMERCIABILITÀ O IDONEITÀ PER UN PARTICOLARE SCOPO.

  • Usa la forma plurale (discussions)
  • Separa più parole con il trattino basso (access_tokens)
  • Per le tabelle delle relazioni, unisci i due nomi di tabella in forma singolare con un trattino basso in ordine alfabetico (es. discussion_user)

CSS

Le classi CSS di Flarum seguono più o meno il SUIT CSS naming conventions con il formato .ComponentName-descendentName--modifierName.

Traduzioni

Utilizziamo formati chiave standard per denominare le chiavi di traduzione in modo descrittivo e coerente.

Contratto di licenza del collaboratore

Contribuendo con il tuo codice a Flarum, concedi alla Flarum Foundation (Stichting Flarum) una licenza non esclusiva, irrevocabile, mondiale, esente da royalty, cedibile in sublicenza e trasferibile sotto tutti i tuoi diritti di proprietà intellettuale rilevanti (inclusi copyright, brevetto e qualsiasi altro diritto ), per utilizzare, copiare, preparare opere derivate, distribuire ed eseguire pubblicamente e visualizzare i Contributi in base a qualsiasi termine di licenza, inclusi, a titolo esemplificativo: (a) licenze open source come la licenza MIT; e (b) licenze binarie, proprietarie o commerciali. Fatta eccezione per le licenze qui concesse, ti riservi tutti i diritti, titoli e interessi relativi al Contributo.

Confermi di essere in grado di concederci questi diritti. Dichiari di essere legalmente autorizzato a concedere la licenza di cui sopra. Se il tuo datore di lavoro ha diritti sulla proprietà intellettuale che crei, dichiari di aver ricevuto il permesso di effettuare i Contributi per conto di quel datore di lavoro, o che il tuo datore di lavoro ha rinunciato a tali diritti per i Contributi.

Dichiari che i Contributi sono tue opere d'autore originali e, per tua conoscenza, nessun'altra persona può rivendicare, o ha il diritto di rivendicare, alcun diritto su qualsiasi invenzione o brevetto relativo ai Contributi. Dichiari inoltre di non essere legalmente obbligato, sia stipulando un contratto che in altro modo, in qualsiasi circostanza che sia in conflitto con i termini di questa licenza.

La Fondazione Flarum riconosce che, ad eccezione di quanto esplicitamente descritto nel presente Accordo, qualsiasi Contributo fornito è "COSÌ COM'È", SENZA GARANZIE O CONDIZIONI DI ALCUN TIPO, ESPLICITE O IMPLICITE, INCLUSE, SENZA LIMITAZIONE, ALCUNA GARANZIA O CONDIZIONE DI TITOLO, NON VIOLAZIONE, COMMERCIABILITÀ O IDONEITÀ PER UN PARTICOLARE SCOPO.