Jak współtworzyć kod

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 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 i ewentualnie skorzystać z jednego z wielu klientów graficznych.

Przygotowanie środowiska i repozytorium

1. na GitHubie utwórz fork repozytorium pakietu, który zamierzasz zmodyfikować
2. to repozytorium sklonujesz na swój komputer
3. zainstaluj zależności, w tym Nette Testera, 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
4. zmiany zapisz (commituj) z opisem w tym formacie

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 (PR)
3. podaj w opisie wystarczająco informacji

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

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:

git checkout -b new_branch_name v3.2.1

Standardy kodowania

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

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:

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