Contribuția la cod

Intenționați să contribuiți la Nette Framework și trebuie să vă familiarizați cu regulile și procedurile? Acest ghid pentru începători vă va ghida prin pașii pentru a contribui eficient la cod, a lucra cu depozitele și a implementa modificări.

Procedura

Pentru a contribui la cod, este esențial să aveți un cont pe GitHub și să fiți familiarizați cu elementele de bază ale lucrului cu sistemul de control al versiunilor Git. Dacă nu sunteți familiarizat cu Git, puteți consulta Ghidul git – the simple guide și puteți lua în considerare utilizarea unuia dintre numeroșii clienți grafici.

Pregătirea mediului și a depozitului

  1. Pe GitHub, creați un fork al depozitului de pachete pe care intenționați să îl modificați
  2. Clonați acest depozit pe computerul dvs.
  3. Instalați dependențele, inclusiv Nette Tester, utilizând comanda composer install
  4. Verificați dacă testele funcționează, rulând composer tester
  5. Creați o nouă ramură bazată pe cea mai recentă versiune lansată

Implementarea propriilor modificări

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

  1. Implementați modificările dorite și nu uitați de teste
  2. Asigurați-vă că testele se execută cu succes folosind composer tester
  3. Verificați dacă codul respectă standardele de codare
  4. Salvați (confirmați) modificările cu o descriere în acest format

Puteți crea mai multe comenzi, câte una pentru fiecare etapă logică. Fiecare commit ar trebui să fie semnificativ în sine.

Trimiterea modificărilor

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

  1. Împingeți modificările pe GitHub în furculița dvs.
  2. De acolo, trimiteți-le la depozitul Nette prin crearea unei pull request (PR)
  3. Furnizați informații suficiente în descriere

Încorporarea feedback-ului

Modificările dvs. sunt acum vizibile pentru ceilalți. Este obișnuit să primiți comentarii cu sugestii:

  1. Țineți evidența modificărilor propuse
  2. Încorporați-le ca noi comenzi sau fuzionați-le cu cele anterioare
  3. Trimiteți din nou comentariile pe GitHub, iar acestea vor apărea automat în cererea de extragere (pull request)

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

Documentație

Dacă ați modificat o funcționalitate 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 în raport cu ultima versiune publicată, adică ultima etichetă din ramură. Pentru eticheta v3.2.1, creați o ramură folosind această comandă:

git checkout -b new_branch_name v3.2.1

Standarde de codificare

Codul dumneavoastră trebuie să respecte standardele de codare utilizate în cadrul Nette Framework. Există un instrument automat disponibil pentru verificarea și corectarea codului. Îl puteți instala global prin Composer într-un dosar la alegere:

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

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

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

Angajare Descriere

În Nette, subiectele de commit au următorul format: Presenter: fixed AJAX detection [Closes #69]

  • area urmată de două puncte
  • scopul angajamentului la timpul trecut; dacă este posibil, începeți cu cuvinte de genul: added, fixed, refactored, changed, removed
  • în cazul în care confirmarea încalcă compatibilitatea retroactivă, adăugați “BC break”
  • orice legătură cu sistemul de urmărire a problemelor, cum ar fi (#123) sau [Closes #69]
  • după subiect, poate exista o linie goală, urmată de o descriere mai detaliată, incluzând, de exemplu, linkuri către forum

Descrierea cererii de tip pull request

Atunci când creați un pull request, interfața GitHub vă va permite să introduceți un titlu și o descriere. Furnizați un titlu concis și includeți în descriere cât mai multe informații despre motivele modificării dumneavoastră.

De asemenea, precizați în antet dacă este o caracteristică nouă sau o remediere a unei erori și dacă poate cauza probleme de compatibilitate retroactivă (BC break). Dacă există o problemă conexă, creați un link către aceasta, astfel încât aceasta să fie închisă în momentul aprobării cererii de modificare.

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