Contribuire al codice

Avete intenzione di contribuire al framework Nette e avete bisogno di familiarizzare con le regole e le procedure? Questa guida per principianti vi guiderà attraverso i passaggi per contribuire efficacemente al codice, lavorare con i repository e implementare le modifiche.

Procedura

Per contribuire al codice, è essenziale avere un account su GitHub e conoscere le basi del sistema di controllo di versione Git. Se non si ha familiarità con Git, si può consultare la guida git – the simple guide e prendere in considerazione l'utilizzo di uno dei tanti client grafici.

Preparazione dell'ambiente e del repository

Su GitHub, creare un fork del repository del pacchetto che si intende modificare
Clonare questo repository sul proprio computer
Installare le dipendenze, compreso Nette Tester, usando il comando composer install.
Verificate che i test funzionino eseguendo composer tester
Creare un nuovo ramo basato sull'ultima versione rilasciata

Implementare le proprie modifiche

Ora è possibile apportare le proprie modifiche al codice:

Implementare le modifiche desiderate e non dimenticare i test.
Assicurarsi che i test vengano eseguiti con successo composer tester
Verificare se il codice è conforme agli standard di codifica
Salvare (commit) le modifiche con una descrizione in questo formato

È possibile creare più commit, uno per ogni fase logica. Ogni commit deve essere significativo di per sé.

Invio delle modifiche

Una volta soddisfatti delle modifiche, è possibile inviarle:

Spingere le modifiche su GitHub al proprio fork
Da lì, inviarle al repository di Nette creando una pull request (PR)
Fornire informazioni sufficienti nella descrizione

Incorporare il feedback

I vostri commit sono ora visibili agli altri. È frequente ricevere commenti con suggerimenti:

Tenere traccia delle modifiche proposte
incorporarle come nuovi commit o unirle a quelle precedenti
Ripresentare i commit a GitHub, che appariranno automaticamente nella richiesta di pull.

Non creare mai una nuova richiesta di pull per modificarne una esistente.

Documentazione

Se avete modificato una funzionalità o ne avete aggiunta una nuova, non dimenticate di aggiungerla anche alla documentazione.

Nuovo ramo

Se possibile, apportare le modifiche all'ultima versione rilasciata, cioè all'ultimo tag del ramo. Per il tag v3.2.1, creare un ramo usando questo comando:

git checkout -b new_branch_name v3.2.1

Standard di codifica

Il codice deve essere conforme agli standard di codifica utilizzati da Nette Framework. È disponibile uno strumento automatico per la verifica e la correzione del codice. È possibile installarlo globalmente tramite Composer in una cartella a scelta:

composer create-project nette/coding-standard /path/to/nette-coding-standard

Ora dovreste essere in grado di eseguire lo strumento nel terminale. Il primo comando controlla e il secondo corregge il codice nelle cartelle src e tests nella directory corrente:

/path/to/nette-coding-standard/ecs check
/path/to/nette-coding-standard/ecs check --fix

Descrizione dell'impegno

In Nette, gli argomenti dei commit hanno il seguente formato: Presenter: fixed AJAX detection [Closes #69]

area seguita da due punti
scopo del commit al passato; se possibile, iniziare con parole come: added, fixed, refactored, changed, removed
se il commit rompe la compatibilità all'indietro, aggiungere “BC break”.
qualsiasi collegamento al tracker dei problemi, come (#123) o [Closes #69]
dopo l'oggetto, può esserci una riga vuota seguita da una descrizione più dettagliata, che includa, per esempio, collegamenti al forum

Descrizione della richiesta

Quando si crea una richiesta di pull, l'interfaccia di GitHub consente di inserire un titolo e una descrizione. Fornire un titolo conciso e includere nella descrizione il maggior numero possibile di informazioni sulle ragioni della modifica.

Inoltre, specificare nell'intestazione se si tratta di una nuova funzionalità o di una correzione di un bug e se può causare problemi di retrocompatibilità (BC break). Se esiste un problema correlato, collegarlo ad esso in modo che venga chiuso dopo l'approvazione della richiesta di pull.

- bug fix / new feature?  <!-- #issue numbers, if any -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- highly welcome, see https://nette.org/en/writing -->