Contribuire al codice

State pensando di contribuire al Nette Framework e avete bisogno di conoscere regole e procedure? Questa guida per principianti vi accompagna nei passi per contribuire al codice in modo efficace, lavorare con i repository e realizzare le modifiche.

Procedura

Per contribuire al codice è indispensabile avere un account su GitHub e conoscere le basi del lavoro con il sistema di versionamento Git. Se non conoscete Git, potete consultare git – the simple guide e considerare l'uso di uno dei tanti client grafici.

Preparazione dell'ambiente e del repository

1. Su GitHub create un fork del repository del pacchetto che volete modificare
2. Clonate questo repository sul vostro computer
3. Installate le dipendenze, compreso Nette Tester, con il comando composer install
4. Verificate che i test funzionino lanciando composer tester
5. Create un Nuovo ramo basato sull'ultima versione rilasciata

Realizzazione delle vostre modifiche

Ora potete fare le vostre modifiche al codice:

1. Realizzate le modifiche desiderate e non dimenticate i test
2. Assicuratevi che i test passino con composer tester
3. Verificate che il codice rispetti gli Standard di codifica
4. Salvate (commit) le modifiche con una descrizione in questo formato

Potete creare più commit, uno per ogni passo logico. Ogni commit dovrebbe avere senso da solo.

Invio delle modifiche

Quando siete soddisfatti delle modifiche, potete inviarle:

1. Inviate (push) le modifiche su GitHub nel vostro fork
2. Da lì proponetele al repository di Nette creando una pull request (PR)
3. Nella descrizione fornite informazioni sufficienti

Incorporare i feedback

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

1. Seguite le modifiche proposte
2. Incorporatele come nuovi commit oppure uniteli con i precedenti
3. Inviate di nuovo i commit su GitHub e compariranno automaticamente nella pull request

Non create mai una nuova pull request per modificarne una esistente.

Documentazione

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

Nuovo ramo

Se possibile, fate le modifiche a partire dall'ultima versione rilasciata, cioè dall'ultimo tag del ramo. Per il tag v3.2.1 create un ramo con questo comando:

git checkout -b nome_nuovo_ramo v3.2.1

Standard di codifica

Il vostro codice deve rispettare lo standard di codifica usato nel Nette Framework. Per verificare e correggere automaticamente il vostro codice usate lo strumento Nette Coding Standard, dove trovate anche le istruzioni di installazione e uso.

Descrizione del commit

In Nette il soggetto dei commit ha questo formato: Presenter: fixed AJAX detection [Closes #69]

• L'area seguita dai due punti
• Lo scopo del commit al passato; se possibile cominciate con parole come: “added (nuova funzionalità)”, “fixed (correzione)”, “refactored (modifica del codice senza cambio di comportamento)”, “changed”, “removed”
• Se il commit rompe la retrocompatibilità, aggiungete “BC break”
• Un eventuale link all'issue tracker, per esempio (#123) oppure [Closes #69]
• Dopo il soggetto può esserci una riga vuota seguita da una descrizione più dettagliata, comprensiva per esempio di link al forum

Descrizione della pull request

Quando create una pull request, l'interfaccia di GitHub vi permette di inserire un titolo e una descrizione. Indicate un titolo conciso e mettete nella descrizione quante più informazioni possibili sui motivi della vostra modifica.

Indicate inoltre nell'intestazione se si tratta di una nuova funzionalità o di una correzione di bug e se può causare problemi di retrocompatibilità (BC break). Se esiste un issue collegato, mettete un link a esso perché venga chiuso all'approvazione della pull request.

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