Jak přispět do kódu

Chystáte se přispět do Nette Frameworku a potřebujete se zorientovat v pravidlech a postupech? Tento průvodce pro začátečníky vám krok za krokem ukáže, jak efektivně přispívat do kódu, pracovat s repozitáři a implementovat změny.

Postup

Pro přispívání do kódu je nezbytné mít účet na GitHub a být obeznámen se základy práce s verzovacím systémem Git. Pokud neovládáte práci s Gitem, můžete se podívat na průvodce git – the simple guide a případně využít některého z mnoha grafických klientů.

Příprava prostředí a repozitáře

  1. na GitHubu si vytvořte fork repositáře balíčku, který se chystáte upravit
  2. tento repositář naklonujete na svůj počítač
  3. nainstalujte závislosti, včetně Nette Testeru, pomocí příkazu composer install
  4. zkontrolujte, že testy fungují, spuštěním composer tester
  5. vytvořte si novou větev založenou na poslední vydané verzi

Implementace vlastních změn

Nyní můžete provést své vlastní úpravy kódu:

  1. naprogramujte požadované změny a nezapomeňte na testy
  2. ujistěte se, že testy proběhnou úspěšně, pomocí composer tester
  3. zkontrolujte, zda kód splňuje kódovací standard
  4. změny uložte (commitněte) s popisem v tomto formátu

Můžete vytvořit několik commitů, jeden pro každý logický krok. Každý commit by měl být smysluplný samostatně.

Odeslání změn

Jakmile budete se změnami spokojeni, můžete je odeslat:

  1. odešlete (pushněte) změny na GitHub do vašeho forku
  2. odtud je odešlete do Nette repositáře vytvořením pull request (PR)
  3. uveďte v popisu dostatek informací

Zapracování připomínek

Vaše commity nyní uvidí i ostatní. Je běžné, že dostanete komentáře s připomínkami:

  1. sledujte navrhované úpravy
  2. zapracujte je jako nové commity nebo je slučte s předchozími
  3. znovu odešlete commity na GitHub a automaticky se objeví v pull requestu

Nikdy nevytvářejte nový pull request kvůli úpravě stávajícího.

Dokumentace

Pokud jste změnili funkčnost nebo přidali novou, nezapomeňte ji také přidat do dokumentace.

Nová větev

Pokud je to možné, provádějte změny vůči poslední vydané verzi, tj. poslednímu tagu v dané větvi. Pro tag v3.2.1 vytvoříte větev tímto příkazem:

git checkout -b new_branch_name v3.2.1

Coding Standards

Váš kód musí splňovat coding standard používaný v Nette Framework. Pro kontrolu a opravu kódu je k dispozici automatický nástroj. Lze jej nainstalovat přes Composer globálně do vámi zvolené 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. Prvním příkazem zkontrolujete a druhým i opravíte kód ve složkách src a tests v aktuálním adresáři:

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

Popis komitu

V Nette mají předměty komitů formát: Presenter: fixed AJAX detection [Closes #69]

  • 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
  • pokud commit přeruší zpětnou kompatibilitu, doplňte „BC break“
  • případná vazba na issue tracker jako (#123) nebo [Closes #69]
  • za subjektem může následovat jeden volný řádek a poté podrobnější popis včetně třeba odkazů na fórum

Popis pull requestu

Při vytváření pull requestu vám rozhraní GitHubu umožní zadat název a popis. Uveďte výstižný název a v popisu poskytněte co nejvíce informací o důvodech pro vaši změnu.

Zobrazí se také záhlaví, kde specifikujte, zda se jedná o novou funkci nebo opravu chyby a zda může dojít k narušení zpětné kompatibility (BC break). Pokud je k dispozici související problém (issue), odkazujte na něj, aby byl uzavřen po schválení pull requestu.

- 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. Dokumentace
  2. Staňte se přispěvatelem do Nette
  3. Jak přispět do kódu