Kako prispevati h kodi

Se pripravljate prispevati k Nette Frameworku in potrebujete orientacijo glede pravil in postopkov? Ta vodnik za začetnike vam bo korak za korakom pokazal, kako učinkovito prispevati h kodi, delati z repozitoriji in implementirati spremembe.

Postopek

Za prispevanje h kodi je nujno imeti račun na GitHub in biti seznanjen z osnovami dela z verzijskim sistemom Git. Če ne obvladate dela z Gitom, si lahko ogledate vodnik git – the simple guide in po potrebi uporabite katerega od mnogih grafičnih klientov.

Priprava okolja in repozitorija

1. na GitHubu si ustvarite fork repozitorija paketa, ki ga nameravate urejati
2. ta repozitorij klonirajte na svoj računalnik
3. namestite odvisnosti, vključno z Nette Testerjem, z ukazom composer install
4. preverite, ali testi delujejo, z zagonom composer tester
5. ustvarite si novo vejo, ki temelji na zadnji izdani različici

Implementacija lastnih sprememb

Zdaj lahko izvedete svoje lastne prilagoditve kode:

1. sprogramirajte zahtevane spremembe in ne pozabite na teste
2. prepričajte se, da testi uspešno potekajo, z uporabo composer tester
3. preverite, ali koda ustreza standardom kodiranja
4. spremembe shranite (commitnite) z opisom v tem formatu

Lahko ustvarite več commitov, enega za vsak logični korak. Vsak commit bi moral biti smiseln sam po sebi.

Pošiljanje sprememb

Ko boste s spremembami zadovoljni, jih lahko pošljete:

1. pošljite (pushnite) spremembe na GitHub v vaš fork
2. od tam jih pošljite v Nette repozitorij z ustvarjanjem pull requesta (PR)
3. v opisu navedite dovolj informacij

Vključevanje pripomb

Vaše commite bodo zdaj videli tudi drugi. Običajno je, da boste prejeli komentarje s pripombami:

1. spremljajte predlagane prilagoditve
2. vključite jih kot nove commite ali jih združite s prejšnjimi
3. ponovno pošljite commite na GitHub in samodejno se bodo pojavili v pull requestu

Nikoli ne ustvarjajte novega pull requesta zaradi urejanja obstoječega.

Dokumentacija

Če ste spremenili funkcionalnost ali dodali novo, je ne pozabite tudi dodati v dokumentacijo.

Nova veja

Če je mogoče, izvajajte spremembe glede na zadnjo izdano različico, tj. zadnjo oznako (tag) v dani veji. Za oznako v3.2.1 ustvarite vejo s tem ukazom:

git checkout -b new_branch_name v3.2.1

Standardi kodiranja

Vaša koda mora ustrezati standardu kodiranja, ki se uporablja v Nette Frameworku. Za preverjanje in popravljanje kode je na voljo samodejno orodje. Lahko ga namestite prek Composerja globalno v mapo po vaši izbiri:

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

Zdaj bi morali imeti možnost zagnati orodje v terminalu. S prvim ukazom preverite in z drugim tudi popravite kodo v mapah src in tests v trenutnem imeniku:

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

Opis commita

V Nette imajo predmeti commitov format: Presenter: fixed AJAX detection [Closes #69]

• področje, ki mu sledi dvopičje
• namen commita v preteklem času, če je mogoče, začnite z besedo: »added« (dodana nova lastnost), »fixed« (popravek), »refactored« (sprememba v kodi brez spremembe obnašanja), changed, removed
• če commit prekine povratno združljivost, dodajte »BC break«
• morebitna povezava z issue trackerjem kot (#123) ali [Closes #69]
• za subjektom lahko sledi ena prosta vrstica in nato podrobnejši opis, vključno na primer s povezavami na forum

Opis pull requesta

Pri ustvarjanju pull requesta vam vmesnik GitHub omogoča vnos naslova in opisa. Navedite jedrnat naslov in v opisu podajte čim več informacij o razlogih za vašo spremembo.

Prikazala se bo tudi glava, kjer določite, ali gre za novo funkcijo ali popravek napake in ali lahko pride do prekinitve povratne združljivosti (BC break). Če obstaja povezan problem (issue), se nanj sklicujte, da bo zaprt po odobritvi pull requesta.

- bug fix / new feature?  <!-- #številke issue-jev, če obstajajo -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- zelo dobrodošlo, glej https://nette.org/en/writing -->