Jak współtworzyć kod
********************

.[perex]
Zamierzasz współtworzyć Nette Framework i potrzebujesz zorientować się w zasadach i procedurach? Ten przewodnik dla początkujących krok po kroku pokaże Ci, jak efektywnie współtworzyć kod, pracować z repozytoriami i implementować zmiany.


Procedura
=========

Aby współtworzyć kod, niezbędne jest posiadanie konta na [GitHub|https://github.com] i znajomość podstaw pracy z systemem kontroli wersji Git. Jeśli nie znasz pracy z Gitem, możesz zapoznać się z przewodnikiem [git - the simple guide |https://rogerdudler.github.io/git-guide/] i ewentualnie skorzystać z jednego z wielu [klientów graficznych |https://git-scm.com/downloads/guis].


Przygotowanie środowiska i repozytorium
---------------------------------------

1) na GitHubie utwórz [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] repozytorium [pakietu |www:packages], który zamierzasz zmodyfikować
2) to repozytorium [sklonujesz |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] na swój komputer
3) zainstaluj zależności, w tym [Nette Testera |tester:], za pomocą polecenia `composer install`
4) sprawdź, czy testy działają, uruchamiając `composer tester`
5) utwórz [#nową gałąź] opartą na ostatniej wydanej wersji


Implementacja własnych zmian
----------------------------

Teraz możesz wprowadzić własne modyfikacje kodu:

1) zaprogramuj wymagane zmiany i nie zapomnij o testach
2) upewnij się, że testy przechodzą pomyślnie, za pomocą `composer tester`
3) sprawdź, czy kod spełnia [standard kodowania |#Standardy kodowania]
4) zmiany zapisz (commituj) z opisem w [tym formacie |#Opis commita]

Możesz utworzyć kilka commitów, jeden dla każdego logicznego kroku. Każdy commit powinien być sensowny samodzielnie.


Wysyłanie zmian
---------------

Gdy będziesz zadowolony ze zmian, możesz je wysłać:

1) wyślij (pushnij) zmiany na GitHub do swojego forka
2) stamtąd wyślij je do repozytorium Nette, tworząc [pull request|https://help.github.com/articles/creating-a-pull-request] (PR)
3) podaj w opisie [wystarczająco informacji |#Opis pull requesta]


Wprowadzanie uwag
-----------------

Twoje commity teraz zobaczą również inni. Jest to normalne, że otrzymasz komentarze z uwagami:

1) śledź proponowane modyfikacje
2) wprowadź je jako nowe commity lub [połącz z poprzednimi |https://help.github.com/en/github/using-git/about-git-rebase]
3) ponownie wyślij commity na GitHub, a automatycznie pojawią się w pull requeście

Nigdy nie twórz nowego pull requesta w celu modyfikacji istniejącego.


Dokumentacja
------------

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


Nowa gałąź
==========

Jeśli to możliwe, wprowadzaj zmiany względem ostatniej wydanej wersji, tj. ostatniego tagu w danej gałęzi. Dla tagu `v3.2.1` utworzysz gałąź tym poleceniem:

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


Standardy kodowania
===================

Twój kod musi spełniać [standard kodowania |coding standard] używany w Nette Framework. Do kontroli i poprawy kodu dostępne jest automatyczne narzędzie. Można je zainstalować za pomocą Composera **globalnie** w wybranym przez siebie folderze:

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

Teraz powinieneś móc uruchomić narzędzie w terminalu. Pierwszym poleceniem sprawdzisz, a drugim również poprawisz 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 commita
============

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

- obszar, po którym następuje dwukropek
- cel commita w czasie przeszłym, jeśli to możliwe, zacznij od słowa: "added (dodana nowa właściwość)", "fixed (poprawka)", "refactored (zmiana w kodzie bez zmiany zachowania)", changed, removed
- jeśli commit przerywa kompatybilność wsteczną, dodaj "BC break"
- ewentualne powiązanie z issue trackerem, jak `(#123)` lub `[Closes #69]`
- po temacie może nastąpić jedna wolna linia, a następnie bardziej szczegółowy opis, w tym np. linki do forum


Opis pull requesta
==================

Podczas tworzenia pull requesta interfejs GitHubu pozwoli Ci wprowadzić tytuł i opis. Podaj zwięzły tytuł, a w opisie dostarcz jak najwięcej informacji o powodach Twojej zmiany.

Wyświetli się również nagłówek, w którym określ, czy jest to nowa funkcja, czy poprawka błędu i czy może dojść do naruszenia kompatybilności wstecznej (BC break). Jeśli istnieje powiązany problem (issue), odwołaj się do niego, aby został zamknięty po zatwierdzeniu pull requesta.

```
- bug fix / new feature?  <!-- #numery issue, jeśli istnieją -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- bardzo mile widziane, zobacz https://nette.org/en/writing -->
```


{{priority: -1}}