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
- na GitHubie utwórz fork repozytorium pakietu, który zamierzasz zmodyfikować
- to repozytorium sklonujesz na swój komputer
- zainstaluj zależności, w tym Nette Testera, za pomocą
polecenia
composer install
- sprawdź, czy testy działają, uruchamiając
composer tester
- utwórz nową gałąź opartą na ostatniej wydanej wersji
Implementacja własnych zmian
Teraz możesz wprowadzić własne modyfikacje kodu:
- zaprogramuj wymagane zmiany i nie zapomnij o testach
- upewnij się, że testy przechodzą pomyślnie, za pomocą
composer tester
- sprawdź, czy kod spełnia standard kodowania
- 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ć:
- wyślij (pushnij) zmiany na GitHub do swojego forka
- stamtąd wyślij je do repozytorium Nette, tworząc pull request (PR)
- podaj w opisie wystarczająco informacji
Wprowadzanie uwag
Twoje commity teraz zobaczą również inni. Jest to normalne, że otrzymasz komentarze z uwagami:
- śledź proponowane modyfikacje
- wprowadź je jako nowe commity lub połącz z poprzednimi
- 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, fixed, refactored, 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 -->