Navrhování změn v kódu

Nette Framework používá Git a GitHub jako úložiště pro kód. Nejlepší způsob, jak přispět, je provést změny ve vaší větvi a poté poslat pull request (PR) na GitHub. Tento dokument shrnuje hlavní kroky jak na to.

Příprava prostředí

Nejprve si forkněte Nette z GitHubu. Pečlivě nastavte prostředí Gitu, nakonfigurujte své uživatelské jméno a e-mail, tyto údaje vás budou identifikovat v historii změn kódu.

Editace kódu

Než začnete programovat, vytvořte si novou větev.

git checkout -b new_branch_name

A můžete začít upravovat kód.

Pokud je to možné, dělejte změny oproti poslední vydané verzi.

Testování změn

Nainstalujte si Nette Tester. Nejjednodušší je zavolat composer install v kořenovém adresáři repositáře. Nyní byste měli být schopni spustit testy v terminálu pomocí ./vendor/bin/tester.

Některé testy mohou selhat kvůli chybějícímu php.ini. Proto byste měli volat Tester s parametrem -c a zadat cestu k php.ini, například ./vendor/bin/tester -c ./tests/php.ini.

Poté, co funguje spouštění testů, můžete implementovat vlastní změny v kódu. Další informace o testování pomocí nástroje Nette Tester najdete v jeho dokumentaci.

Coding Standards

Váš kód musí splňovat coding standard používaný v Nette Framework. Je to snadné, protože existuje automatický nástroj pro kontrolu a opravu kódu. Lze jej nainstalovat přes Composer do vámi zvolené globální složky:

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

Nyní byste měli mít možnost spustit nástroj v terminálu. Tímto příkazem například zkontrolujete a opravíte kód ve složkách src a tests v aktuálním adresáři:

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

Komitování změn

Po úpravě kódu jej tzv. komitujete. Komitů klidně vytvořte několik, pro každý logický krok jeden. Každý commit by měl být smysluplný sám o sobě. Měl by zahrnovat i testy.

Zkontrolujte prosím, zda váš kód odpovídá pravidlům:

Kód nevytváří žádné chyby
Neporušuje žádné testy.
Změny v kódu jsou testované.
Neděláte zbytečné změny v bílém prostoru.

Popis komitu by měl odpovídat formátu Latte: fixed multi-template rendering [Closes #69], tj.

oblast následovaná dvojtečkou
účel commitu v minulém čase, je-li to možné, začněte slovem: added, fixed, refactored, changed, removed
případná vazba na issue tracker
pokud commit přeruší zpětnou kompatibilitu, doplňte „BC break“
za subjektem může být jeden volný řádek a podrobnější popis včetně odkazů na fórum.

Posílání Pull requestu

Pokud jste se změnami spokojeni, odešlete je na GitHub.

git push původu new_branch_name

Kód už je veřejně dostupný, ale musíte je odeslat do hlavní větve (masteru) v repozitáři Nette. Udělejte tzv. pull request. Každá žádost má název a popis. Uveďte prosím výstižný název. Například „Zabezpečení signálů proti útoku CSRF“.

Popis pull requestu by měl obsahovat další specifické informace:

- 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 -->

Upravte prosím tabulku informací tak, aby odpovídala vašemu pull requestu.

uveďte, jestli jde o novou funkci, nebo o bugfix
odkažte na případnou související issue, která bude uzavřena po schválení pull requestu.
uveďte, zda požadavek potřebuje dokumentační změny, pokud ano, uveďte odkazy na příslušné issue. Změnu dokumentace nemusíte dělat okamžitě, ale pull request nebude přijat, pokud je zapotřebí změnit dokumentaci. Změna dokumentace musí být připravena pro anglickou dokumentaci, jiné jazykové mutace jsou nepovinné.
uveďte, zda změna v kódu způsobí BC break. Vezměte prosím v úvahu všechno, co jej může způsobit.

Konečná tabulka by mohla vypadat takto:

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

Přepracování změn

Je běžné, že budete dostávat komentáře s připomínkami. Sledujte navrhované změny a zapracujte je. Navrhované změny můžete přidávat jako nové commity a sloučit je s předchozími. Viz kapitola Interactive rebase na stránce GitHubu. Poté opět odešlete commity na GitHub a vše se automaticky objeví v pull requestu.