Proposta di modifica del codice

Nette Framework utilizza Git e GitHub per la manutenzione del codice base. Il modo migliore per contribuire è fare il commit delle modifiche al proprio fork e poi fare una richiesta di pull su GitHub. Questo documento riassume i passi principali per contribuire con successo.

Preparazione dell'ambiente

Iniziare con il fork di Nette su GitHub. Impostate con cura il vostro ambiente Git locale, configurate il vostro nome utente e la vostra e-mail; queste credenziali identificheranno le vostre modifiche nella cronologia del framework Nette.

Lavorare sulla patch

Prima di iniziare a lavorare sulla patch, create un nuovo ramo per le vostre modifiche.

git checkout -b new_branch_name

È possibile lavorare sulla modifica del codice.

Se possibile, apportate le modifiche dall'ultima versione rilasciata.

Testare le modifiche

È necessario installare Nette Tester. Il modo più semplice è chiamare composer install nella root del repository. Ora si dovrebbe essere in grado di eseguire i test con ./vendor/bin/tester nel terminale.

Alcuni test potrebbero fallire a causa della mancanza di php.ini. Pertanto, si dovrebbe chiamare il runner con il parametro -c e specificare il percorso di php.ini, per esempio ./vendor/bin/tester -c ./tests/php.ini.

Dopo aver eseguito i test, è possibile implementare i propri o modificare i fallimenti per adattarli al nuovo comportamento. Per saperne di più sui test con Nette Tester, consultare la pagina della documentazione.

Standard di codifica

Il codice deve seguire gli standard di codifica utilizzati in Nette Framework. È facile, perché c'è un programma di controllo e correzione automatico. Può essere installato tramite Composer nella cartella globale scelta:

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

Ora si dovrebbe essere in grado di eseguire lo strumento nel terminale. Ad esempio, questo comando controlla e corregge il codice nelle cartelle src e tests della directory corrente:

/path/to/nette-coding-standard/ecs check src tests --config /path/to/nette-coding-standard/coding-standard-php71.yml --fix

Applica le modifiche

Dopo aver modificato il codice, è necessario eseguire il commit delle modifiche. Creare più commit, uno per ogni passo logico. Ogni commit deve essere utilizzabile così com'è, senza altri commit. Quindi, anche i test appropriati devono essere inclusi nello stesso commit.

Verificare che il codice sia conforme alle regole:

• Il codice non genera errori
• Il codice non infrange alcun test.
• La modifica del codice è testata.
• Non state apportando modifiche inutili allo spazio bianco.

Il messaggio di commit dovrebbe seguire il formato Latte: fixed multi template rendering [Closes # 69] cioè

• un'area seguita da due punti
• lo scopo del commit in passato, se possibile, iniziare con “added.”, “fixed.”, “refactored.”, changed, removed
• eventuale link al tracker dei problemi
• se il commit annulla la retrocompatibilità, aggiungere “BC break”.
• può esserci una riga libera dopo l'oggetto e una descrizione più dettagliata, compresi i link al forum.

Richiedere i commit

Se si è soddisfatti delle modifiche e dei commit apportati al codice, è necessario inviare i commit a GitHub.

git push origin new_branch_name

Le modifiche sono presenti pubblicamente, tuttavia è necessario proporre le proprie modifiche per l'integrazione nel ramo master di Nette. Per farlo, bisogna fare una richiesta di pull. Ogni richiesta di pull ha un titolo e una descrizione. Si prega di fornire un titolo descrittivo. Spesso è simile al nome del ramo, ad esempio “Messa in sicurezza dei segnali contro gli attacchi CSRF”.

La descrizione della richiesta di pull dovrebbe contenere alcune informazioni più specifiche sulle modifiche al codice:

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

Modificare la tabella delle informazioni per adattarla alla richiesta di pull. Commenti a ogni voce dell'elenco:

• Dice se la richiesta di pull aggiunge una caratteristica o se è un bugfix.
• Riferisce eventualmente un problema correlato, che sarà chiuso dopo l'unione della richiesta di pull.
• Dice se la richiesta di pull necessita di modifiche alla documentazione, se sì, fornire i riferimenti alle richieste di pull appropriate. Non è necessario fornire immediatamente la modifica della documentazione, tuttavia la richiesta di pull non sarà unita se la modifica della documentazione è necessaria. La modifica della documentazione deve essere preparata per la documentazione in inglese, le altre mutazioni linguistiche sono opzionali.
• Dice se la richiesta di pull crea una rottura del BC. Si prega di considerare tutto ciò che modifica l'interfaccia pubblica come un'interruzione del BC.

La tabella finale potrebbe essere simile a:

- bug fix? no
- new feature? yes   issue #123
- BC break? no

Rielaborazione delle modifiche

È molto comune ricevere commenti alle proprie modifiche al codice. Cercate di seguire le modifiche proposte e rielaborate i vostri commit per farlo. È possibile fare il commit delle modifiche proposte come nuovi commit e poi schiacciarli su quelli precedenti. Vedere il capitolo sul rebase interattivo su GitHub. Dopo aver effettuato il rebase delle modifiche, spingere con forza le modifiche al proprio fork remoto: tutto verrà automaticamente propagato alla richiesta di pull.