Wkład do kodu
*************

.[perex]
Planujesz wnieść swój wkład do Nette Framework i potrzebujesz zapoznać się z zasadami i procedurami? Ten przewodnik dla początkujących poprowadzi Cię przez kroki, które pozwolą Ci efektywnie współtworzyć kod, pracować z repozytoriami i wprowadzać zmiany.


Procedura .[#toc-procedure]
===========================

Aby wnieść wkład do kodu, konieczne jest posiadanie konta na [GitHubie |https://github.com] i znajomość podstaw pracy z systemem kontroli wersji Git. Jeśli nie jesteś zaznajomiony z Gitem, możesz sprawdzić [git - prosty przewodnik |https://rogerdudler.github.io/git-guide/] i rozważyć użycie jednego z wielu [graficznych klientów |https://git-scm.com/downloads/guis].


Przygotowanie środowiska i repozytorium .[#toc-preparing-the-environment-and-repository]
----------------------------------------------------------------------------------------

1) Na GitHubie utwórz [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] [repozytorium pakietów |www:packages], które zamierzasz zmodyfikować
2) [Sklonuj |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] to repozytorium na swój komputer
3) Zainstaluj zależności, w tym [Nette Tester |tester:], używając polecenia `composer install`
4) Sprawdź, czy testy działają, uruchamiając `composer tester`
5) Utwórz [nową gałąź |#New Branch] opartą na najnowszej wydanej wersji


Wdrażanie własnych zmian .[#toc-implementing-your-own-changes]
--------------------------------------------------------------

Teraz możesz wprowadzić własne poprawki do kodu:

1) Zaimplementuj pożądane zmiany i nie zapomnij o testach
2) Upewnij się, że testy przebiegają pomyślnie używając `composer tester`
3) Sprawdź, czy kod spełnia [standardy kodowania |#coding standards]
4) Zapisz (commit) zmiany z opisem w [tym formacie |#Commit Description]

Możesz stworzyć wiele commitów, po jednym dla każdego logicznego kroku. Każdy commit powinien być znaczący sam w sobie.


Przesyłanie zmian .[#toc-submitting-changes]
--------------------------------------------

Gdy zmiany są zadowalające, można je przesłać:

1) Przesuń zmiany na GitHub do swojego forka
2) Stamtąd prześlij je do repozytorium Nette, tworząc [pull request|https://help.github.com/articles/creating-a-pull-request] (PR)
3) Podaj [wystarczającą ilość informacji |#pull request description] w opisie


Uwzględnianie informacji zwrotnych .[#toc-incorporating-feedback]
-----------------------------------------------------------------

Twój commit jest teraz widoczny dla innych. Powszechne jest otrzymywanie komentarzy z sugestiami:

1) Śledzić proponowane zmiany
2) Włącz je jako nowe commity lub [połącz z poprzednimi |https://help.github.com/en/github/using-git/about-git-rebase]
3) Prześlij ponownie commit na GitHub, a automatycznie pojawi się on w żądaniu ściągnięcia.

Nigdy nie twórz nowego pull requesta, aby zmodyfikować istniejący.


Dokumentacja .[#toc-documentation]
----------------------------------

Jeśli zmieniłeś funkcjonalność lub dodałeś nową, nie zapomnij [dodać jej |documentation] również [do dokumentacji |documentation].


Nowa gałąź .[#toc-new-branch]
=============================

Jeśli to możliwe, dokonuj zmian względem najnowszej wydanej wersji, czyli ostatniego tagu w gałęzi. Dla tagu v3.2.1 utwórz gałąź używając tego polecenia:

```shell
git checkout -b new_branch_name v3.2.1
```


Standardy kodowania .[#toc-coding-standards]
============================================

Twój kod musi spełniać [standardy kodowania |coding standard] stosowane w Nette Framework. Dostępne jest automatyczne narzędzie do sprawdzania i poprawiania kodu. Możesz je zainstalować **globalnie** poprzez Composera do wybranego przez siebie folderu:

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

Teraz powinieneś być w stanie uruchomić narzędzie w terminalu. Pierwsze polecenie sprawdza, a drugie naprawia kod w folderach `src` i `tests` w bieżącym katalogu:

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


Opis zobowiązania .[#toc-commit-description]
============================================

W Nette, tematy commitów mają następujący format: `Presenter: fixed AJAX detection [Closes #69]`

- obszar, po którym następuje dwukropek
- cel commitu w czasie przeszłym; jeśli to możliwe, zacznij od słów takich jak: added, fixed, refactored, changed, removed
- jeśli commit łamie wsteczną kompatybilność, dodaj "BC break"
- wszelkie połączenia z issue trackerem, takie jak `(#123)` lub `[Closes #69]`
- po temacie może być jedna pusta linia, po której następuje bardziej szczegółowy opis, zawierający np. linki do forum


Opis Pull Request .[#toc-pull-request-description]
==================================================

Podczas tworzenia pull request, interfejs GitHub pozwoli Ci wprowadzić tytuł i opis. Podaj zwięzły tytuł i zawrzyj jak najwięcej informacji w opisie o powodach zmiany.

Określ również w nagłówku, czy jest to nowa funkcja czy poprawka błędu i czy może spowodować problemy z kompatybilnością wsteczną (BC break). Jeśli istnieje powiązany problem, umieść do niego link, aby został zamknięty po zatwierdzeniu pull requesta.

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


{{priority: -1}}