Come contribuire al codice

State pensando di contribuire a Nette Framework e avete bisogno di orientarvi tra le regole e le procedure? Questa guida per principianti vi mostrerà passo dopo passo come contribuire efficacemente al codice, lavorare con i repository e implementare le modifiche.

Procedura

Per contribuire al codice è indispensabile avere un account su GitHub ed essere familiari con le basi del lavoro con il sistema di versionamento Git. Se non conoscete il lavoro con Git, potete consultare la guida git – the simple guide ed eventualmente utilizzare uno dei tanti client grafici.

Preparazione dell'ambiente e del repository

  1. su GitHub, create un fork del repository del pacchetto che intendete modificare
  2. clonate questo repository sul vostro computer
  3. installate le dipendenze, incluso Nette Tester, tramite il comando composer install
  4. verificate che i test funzionino eseguendo composer tester
  5. create un nuovo ramo basato sull'ultima versione rilasciata

Implementazione delle proprie modifiche

Ora potete apportare le vostre modifiche al codice:

  1. programmate le modifiche richieste e non dimenticate i test
  2. assicuratevi che i test vengano eseguiti con successo tramite composer tester
  3. verificate che il codice soddisfi lo standard di codifica
  4. salvate (committate) le modifiche con una descrizione in questo formato

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

Invio delle modifiche

Una volta soddisfatti delle modifiche, potete inviarle:

  1. inviate (push) le modifiche su GitHub al vostro fork
  2. da lì, inviatele al repository Nette creando una pull request (PR)
  3. fornite nella descrizione informazioni sufficienti

Integrazione dei commenti

I vostri commit ora saranno visibili anche agli altri. È comune ricevere commenti con suggerimenti:

  1. seguite le modifiche proposte
  2. integrateli come nuovi commit o uniteli ai precedenti
  3. inviate nuovamente i commit su GitHub e appariranno automaticamente nella pull request

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

Documentazione

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

Nuovo ramo

Se possibile, apportate le modifiche rispetto all'ultima versione rilasciata, ovvero l'ultimo tag nel ramo corrispondente. Per il tag v3.2.1, create un ramo con questo comando:

git checkout -b new_branch_name v3.2.1

Standard di codifica

Il vostro codice deve soddisfare lo standard di codifica utilizzato in Nette Framework. Per controllare e correggere il codice è disponibile uno strumento automatico. Può essere installato tramite Composer globalmente nella cartella da voi scelta:

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

Ora dovreste essere in grado di eseguire lo strumento nel terminale. Con il primo comando controllerete e con il secondo correggerete anche 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 del commit

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

  • area seguita da due punti
  • scopo del commit al passato, se possibile, iniziate con la parola: added (nuova funzionalità aggiunta), fixed (correzione), refactored (modifica del codice senza modifica del comportamento), changed, removed
  • se il commit interrompe la compatibilità all'indietro, aggiungete “BC break”
  • eventuale collegamento all'issue tracker come (#123) o [Closes #69]
  • dopo l'oggetto può seguire una riga vuota e poi una descrizione più dettagliata, inclusi ad esempio link al forum

Descrizione della pull request

Durante la creazione di una pull request, l'interfaccia di GitHub vi consentirà di inserire un titolo e una descrizione. Fornite un titolo conciso e nella descrizione fornite quante più informazioni possibili sui motivi della vostra modifica.

Verrà visualizzata anche un'intestazione in cui specificare se si tratta di una nuova funzionalità o di una correzione di bug e se può verificarsi un'interruzione della compatibilità all'indietro (BC break). Se è disponibile un problema correlato (issue), fatevi riferimento in modo che venga chiuso dopo l'approvazione della pull request.

- correzione bug / nuova funzionalità?  <!-- #numeri issue, se presenti -->
- BC break? sì/no
- doc PR: nette/docs#?    <!-- molto gradito, vedi https://nette.org/en/writing -->
  1. Documentazione
  2. Diventa un contributore di Nette
  3. Come contribuire al codice