Wkład do kodu

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

Aby wnieść wkład do kodu, konieczne jest posiadanie konta na GitHubie i znajomość podstaw pracy z systemem kontroli wersji Git. Jeśli nie jesteś zaznajomiony z Gitem, możesz sprawdzić git – prosty przewodnik i rozważyć użycie jednego z wielu graficznych klientów.

Przygotowanie środowiska i repozytorium

1. Na GitHubie utwórz fork repozytorium pakietów, które zamierzasz zmodyfikować
2. Sklonuj to repozytorium na swój komputer
3. Zainstaluj zależności, w tym Nette Tester, używając polecenia composer install
4. Sprawdź, czy testy działają, uruchamiając composer tester
5. Utwórz nową gałąź opartą na najnowszej wydanej wersji

Wdrażanie własnych zmian

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
4. Zapisz (commit) zmiany z opisem w tym formacie

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

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 (PR)
3. Podaj wystarczającą ilość informacji w opisie

Uwzględnianie informacji zwrotnych

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

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

Nowa gałąź

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:

git checkout -b new_branch_name v3.2.1

Standardy kodowania

Twój kod musi spełniać standardy kodowania 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:

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:

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

Opis zobowiązania

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

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