Predlaganje spremembe kodeksa

Nette Framework za vzdrževanje baze kode uporablja Git in GitHub. Najboljši način za prispevanje je, da svoje spremembe prenesete v svojo vilico in nato v GitHub oddate zahtevek za povleko. Ta dokument povzema glavne korake za uspešno prispevanje.

Priprava okolja

Začnite z viličenjem Nette na GitHubu. Skrbno nastavite lokalno okolje Git, konfigurirajte svoje uporabniško ime in e-pošto, saj bodo te poverilnice identificirale vaše spremembe v zgodovini ogrodja Nette.

Delo na vašem popravku

Preden začnete delati na popravku, ustvarite novo vejo za svoje spremembe.

git checkout -b new_branch_name

Tako lahko delate na spremembi kode.

Če je mogoče, spremembe izvedite iz zadnje izdane različice.

Preizkušanje sprememb

Namestiti morate program Nette Tester. Najlažje je, če v korenskem naslovu skladišča pokličete composer install. Zdaj bi morali biti sposobni izvajati teste s ./vendor/bin/tester v terminalu.

Nekateri testi bodo morda neuspešni zaradi manjkajočega php.ini. Zato morate prožilec poklicati s parametrom -c in navesti pot do php.ini, na primer ./vendor/bin/tester -c ./tests/php.ini.

Ko boste lahko zagnali teste, lahko izvedete svoje ali spremenite neuspešne, da bodo ustrezali novemu obnašanju. Več o testiranju s programom Nette Tester si preberite na strani z dokumentacijo.

Standardi kodiranja

Vaša koda mora upoštevati standard kodiranja, ki se uporablja v okviru Nette. To je enostavno, saj je na voljo samodejni pregledovalnik in popravljalnik. Namestite ga lahko prek programa Composer v izbrani globalni imenik:

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

Zdaj morate biti sposobni zagnati orodje v terminalu. Ta ukaz na primer preveri in popravi kodo v mapah src in tests v trenutnem imeniku:

/path/to/nette-coding-standard/ecs check src tests --config /path/to/nette-coding-standard/coding-standard-php71.yml --fix

Oddajanje sprememb

Ko spremenite kodo, morate spremembe potrditi. Ustvarite več zavez, po eno za vsak logični korak. Vsaka sprememba mora biti uporabna takšna, kot je – brez drugih sprememb. Zato je treba v isti commit vključiti tudi ustrezne teste.

Dvakrat preverite, ali vaša koda ustreza pravilom:

Koda ne ustvarja napak.
Vaša koda ne krši nobenih testov.
Vaša sprememba kode je testirana.
Ne izvajate nekoristnih sprememb v belem polju.

Sporočilo o oddaji mora biti v obliki Latte: fixed multi template rendering [Closes # 69] tj:

področje, ki mu sledi dvopičje
namen oddaje v preteklosti, če je mogoče, začnite z “dodano.”, “popravljeno.”, “refaktorizirano.”, spremenjeno, odstranjeno
morebitna povezava do sledilnika težav
če sprememba prekliče združljivost za nazaj, dodajte “BC break”.
za temo je lahko ena prosta vrstica in podrobnejši opis, vključno s povezavami na forum.

Zahteva za povišanje (Pull-Requesting) za dopolnitve

Če ste zadovoljni s spremembami kode in zavezami, morate svoje zaveze poslati v GitHub.

git push origin new_branch_name

Spremembe so javno dostopne, vendar morate svoje spremembe predlagati za vključitev v glavno vejo Nette. To storite tako, da podate zahtevo za poteg. Vsak zahtevek ima naslov in opis. Navedite nekaj opisnih naslovov. Pogosto je podoben imenu veje, na primer “Zavarovanje signalov pred napadom CSRF”.

Opis zahteve za poteg bi moral vsebovati nekaj bolj specifičnih informacij o vaših spremembah kode:

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

Prosimo, spremenite tabelo z informacijami, da bo ustrezala vaši zahtevi za poteg. Pripombe k vsaki postavki seznama:

Piše, ali zahtevek dodaja funkcijo ali gre za opravek napake.
Sklicuje se na morebitno povezano vprašanje, ki bo zaprto po združitvi zahteve.
Pove, ali je treba v zahtevi za prenos spremeniti dokumentacijo, če je tako, navedite sklice na ustrezne zahteve za prenos. Spremembe dokumentacije vam ni treba zagotoviti takoj, vendar pa zahteva za poteg ne bo združena, če je sprememba dokumentacije potrebna. Sprememba dokumentacije mora biti pripravljena za angleško dokumentacijo, druge jezikovne mutacije niso obvezne.
Pove, če zahtevek za prenos ustvari prekinitev BC. Vse, kar spreminja javni vmesnik, obravnavajte kot prelom BC.

Končna tabela bi lahko bila videti takole:

- bug fix? no
- new feature? yes   issue #123
- BC break? no

Preoblikovanje sprememb

Pogosto se zgodi, da prejmete komentarje k spremembi kode. Poskusite slediti predlaganim spremembam in v ta namen predelajte svoje spremembe. Predlagane spremembe lahko oddate kot nove oddaje in jih nato zmečkate s prejšnjimi. Oglejte si poglavje o interaktivni ponovni vzpostavitvi na spletnem mestu GitHub. Po ponovnem uokvirjanju sprememb za silo potisnite spremembe v oddaljeno vilico, vse se bo samodejno razširilo v zahtevek za povleko (pull request).