Cum să contribuiți la cod

Vă pregătiți să contribuiți la Nette Framework și aveți nevoie să vă orientați în reguli și proceduri? Acest ghid pentru începători vă va arăta pas cu pas cum să contribuiți eficient la cod, să lucrați cu depozite și să implementați modificări.

Procedura

Pentru a contribui la cod este necesar să aveți un cont pe GitHub și să fiți familiarizat cu elementele de bază ale lucrului cu sistemul de versionare Git. Dacă nu stăpâniți lucrul cu Git, puteți consulta ghidul git – the simple guide și eventual să utilizați unul dintre multele clienți grafici.

Pregătirea mediului și a depozitului

  1. pe GitHub creați un fork al depozitului pachetului, pe care urmează să-l modificați
  2. clonați acest depozit pe computerul dvs.
  3. instalați dependențele, inclusiv Nette Tester, folosind comanda composer install
  4. verificați dacă testele funcționează, rulând composer tester
  5. creați o nouă ramură bazată pe ultima versiune lansată

Implementarea propriilor modificări

Acum puteți efectua propriile modificări de cod:

  1. programați modificările dorite și nu uitați de teste
  2. asigurați-vă că testele rulează cu succes, folosind composer tester
  3. verificați dacă codul respectă standardul de codificare
  4. salvați modificările (commit) cu o descriere în acest format

Puteți crea mai multe commit-uri, unul pentru fiecare pas logic. Fiecare commit ar trebui să aibă sens de sine stătător.

Trimiterea modificărilor

Odată ce sunteți mulțumit de modificări, le puteți trimite:

  1. trimiteți (push) modificările pe GitHub în fork-ul dvs.
  2. de acolo le trimiteți către depozitul Nette creând un pull request (PR)
  3. furnizați în descriere suficiente informații

Incorporarea comentariilor

Commit-urile dvs. vor fi acum vizibile și pentru alții. Este obișnuit să primiți comentarii cu observații:

  1. urmăriți modificările propuse
  2. încorporați-le ca noi commit-uri sau combinați-le cu cele anterioare
  3. retrimiteți commit-urile pe GitHub și acestea vor apărea automat în pull request

Nu creați niciodată un nou pull request pentru a modifica unul existent.

Documentație

Dacă ați modificat funcționalitatea sau ați adăugat una nouă, nu uitați să o adăugați și în documentație.

Ramură nouă

Dacă este posibil, efectuați modificările față de ultima versiune lansată, adică ultimul tag din ramura respectivă. Pentru tag-ul v3.2.1 creați o ramură cu această comandă:

git checkout -b new_branch_name v3.2.1

Standarde de codificare

Codul dvs. trebuie să respecte standardul de codificare utilizat în Nette Framework. Pentru verificarea și corectarea codului este disponibil un instrument automat. Acesta poate fi instalat prin Composer global în directorul ales de dvs.:

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

Acum ar trebui să puteți rula instrumentul în terminal. Prima comandă verifică și a doua corectează codul din directoarele src și tests din directorul curent:

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

Descrierea commit-ului

În Nette, subiectele commit-urilor au formatul: Presenter: fixed AJAX detection [Closes #69]

  • zona urmată de două puncte
  • scopul commit-ului la timpul trecut, dacă este posibil, începeți cu cuvântul: added, fixed, refactored, changed, removed
  • dacă commit-ul întrerupe compatibilitatea inversă, adăugați “BC break”
  • eventuală legătură cu issue tracker-ul precum (#123) sau [Closes #69]
  • după subiect poate urma o linie goală și apoi o descriere mai detaliată, inclusiv, de exemplu, linkuri către forum

Descrierea pull request-ului

La crearea unui pull request, interfața GitHub vă permite să introduceți un titlu și o descriere. Furnizați un titlu descriptiv și în descriere oferiți cât mai multe informații despre motivele modificării dvs.

Se va afișa și un antet, unde specificați dacă este vorba despre o nouă funcție sau o corecție de eroare și dacă poate apărea o întrerupere a compatibilității inverse (BC break). Dacă există o problemă (issue) asociată, faceți referire la ea, astfel încât să fie închisă după aprobarea pull request-ului.

- bug fix / new feature?  <!-- #issue numbers, if any -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- highly welcome, see https://nette.org/en/writing -->
  1. Documentație
  2. Deveniți un contribuitor Nette
  3. Cum să contribuiți la cod