Kontrybuowanie do kodu

Planujesz kontrybuować do Nette Framework i musisz zapoznać się z regułami i procedurami? Ten przewodnik dla początkujących przeprowadzi Cię przez kroki, jak efektywnie kontrybuować kod, pracować z repozytoriami i wprowadzać zmiany.

Procedura

Żeby kontrybuować kod, konieczne jest posiadanie konta na GitHubie i znajomość podstaw pracy z systemem kontroli wersji Git. Jeśli nie znasz Gita, możesz zajrzeć do git – the simple guide i rozważyć użycie jednego z wielu klientów graficznych.

Przygotowanie środowiska i repozytorium

1. Na GitHubie utwórz fork repozytorium pakietu, który zamierzasz zmodyfikować
2. Sklonuj to repozytorium na swój komputer
3. Zainstaluj zależności, wraz z Nette Testerem, poleceniem composer install
4. Sprawdź, czy testy działają, uruchamiając composer tester
5. Utwórz nową gałąź na podstawie ostatnio wydanej wersji

Wprowadzanie własnych zmian

Teraz możesz wprowadzać własne poprawki w kodzie:

1. Zaimplementuj pożądane zmiany i nie zapomnij o testach
2. Upewnij się, że testy przechodzą pomyślnie, za pomocą composer tester
3. Sprawdź, czy kod spełnia standardy kodowania
4. Zapisz (zacommituj) zmiany z opisem w tym formacie

Możesz utworzyć wiele commitów, po jednym na każdy logiczny krok. Każdy commit powinien mieć sens sam w sobie.

Zgłaszanie zmian

Gdy jesteś zadowolony ze zmian, możesz je zgłosić:

1. Wypchnij zmiany na GitHuba do swojego forka
2. Stamtąd zgłoś je do repozytorium Nette, tworząc pull request (PR)
3. Podaj w opisie wystarczające informacje

Uwzględnianie uwag

Twoje commity są teraz widoczne dla innych. Często dostaje się komentarze z sugestiami:

1. Śledź proponowane zmiany
2. Uwzględniaj je jako nowe commity albo łącz je z poprzednimi
3. Wypchnij commity ponownie na GitHuba, a pojawią się automatycznie w pull requeście

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

Dokumentacja

Jeśli zmieniłeś funkcjonalność albo dodałeś nową, nie zapomnij dodać jej także do dokumentacji.

Nowa gałąź

Jeśli to możliwe, wprowadzaj zmiany względem ostatnio wydanej wersji, czyli ostatniego tagu w gałęzi. Dla tagu v3.2.1 utwórz gałąź tym poleceniem:

git checkout -b nazwa_nowej_galezi v3.2.1

Standardy kodowania

Twój kod musi spełniać standard kodowania używany w Nette Framework. Do sprawdzenia i automatycznej poprawy kodu użyj narzędzia Nette Coding Standard, gdzie znajdziesz też instrukcje instalacji i użycia.

Opis commitu

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

• Obszar, po nim dwukropek
• Cel commitu w czasie przeszłym; jeśli to możliwe, zaczynaj od słów: “added (nowa funkcja)”, “fixed (poprawka)”, “refactored (zmiana kodu bez zmiany zachowania)”, “changed”, “removed”
• Jeśli commit łamie kompatybilność wsteczną, dodaj “BC break”
• Ewentualny odnośnik do issue trackera, jak (#123) albo [Closes #69]
• Za tematem może być jedna pusta linia, a po niej bardziej szczegółowy opis wraz z, na przykład, odnośnikami do forum

Opis pull requesta

Przy tworzeniu pull requesta interfejs GitHuba pozwoli Ci wpisać tytuł i opis. Podaj zwięzły tytuł i umieść w opisie jak najwięcej informacji o powodach swojej zmiany.

Podaj też w nagłówku, czy chodzi o nową funkcję, czy o poprawkę błędu i czy może to spowodować problemy z kompatybilnością wsteczną (BC break). Jeśli istnieje powiązane issue, podlinkuj je, żeby zostało zamknięte 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 -->