Proponowanie zmiany w kodeksie

Nette Framework używa Git i GitHub do utrzymania bazy kodu. Najlepszym sposobem na wniesienie wkładu w kod jest commitowanie swoich zmian do własnego forka, a następnie zgłoszenie pull request na GitHubie. Ten dokument podsumowuje główne kroki, które należy podjąć, aby skutecznie przyczynić się do rozwoju kodu.

Przygotowanie środowiska

Zacznij od rozwidlenia Nette na GitHubie. Starannie skonfiguruj swoje lokalne środowisko Git, skonfiguruj swoją nazwę użytkownika i e-mail, te poświadczenia będą identyfikować twoje zmiany w historii Nette Framework.

Praca nad twoją łatką

Zanim zaczniesz pracować nad swoim patchem, utwórz nową gałąź dla swoich zmian.

git checkout -b new_branch_name

Możesz pracować nad swoją zmianą kodu.

Jeśli to możliwe, wprowadź zmiany z ostatniej wydanej wersji.

Testowanie zmian

Musisz zainstalować Nette Tester. Najprostszym sposobem jest wywołanie composer install w korzeniu repozytorium. Teraz powinieneś być w stanie uruchomić testy z ./vendor/bin/tester w terminalu.

Niektóre testy mogą się nie powieść z powodu braku php.ini. Dlatego należy wywołać runner z parametrem -c i podać ścieżkę do php.ini, na przykład ./vendor/bin/tester -c ./tests/php.ini.

Po uruchomieniu testów, możesz zaimplementować własne lub zmienić awarie, aby dopasować je do nowego zachowania. Przeczytaj więcej o testowaniu za pomocą Nette Tester na stronie dokumentacji.

Standardy kodowania

Twój kod musi spełniać standardy kodowania używane w Nette Framework. Jest to łatwe, ponieważ istnieje automatyczny checker i fixer. Można go zainstalować poprzez Composer do wybranego przez siebie globalnego katalogu:

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

Teraz powinieneś być w stanie uruchomić narzędzie w terminalu. Na przykład, to polecenie sprawdza i naprawia kod w folderach src i tests w bieżącym katalogu:

/path/to/nette-coding-standard/ecs check src tests --config /path/to/nette-coding-standard/coding-standard-php71.yml --fix

Zobowiązanie do zmiany

Po zmianie kodu, musisz zatwierdzić swoje zmiany. Utwórz więcej commitów, po jednym dla każdego logicznego kroku. Każdy commit powinien nadawać się do użytku jako taki – bez innych commitów. Tak więc, odpowiednie testy powinny być również zawarte w tym samym commicie.

Proszę, sprawdź dwukrotnie czy twój kod pasuje do zasad:

Kod nie generuje żadnych błędów
Twój kod nie łamie żadnych testów.
Twoja zmiana kodu jest przetestowana.
Nie popełniasz bezużytecznych zmian w białej przestrzeni.

Wiadomość o popełnieniu zmiany powinna być zgodna z formatem Latte: fixed multi template rendering [Closes # 69] tj:

obszar, po którym następuje dwukropek
cel commitu w przeszłości, jeśli to możliwe, zacznij od “added.”, “fixed.”, “refactored.”, changed, removed
ewentualny link do issue tracker
jeśli commit anuluje kompatybilność wsteczną, dodaj “BC break”
może być jedna wolna linia po temacie i bardziej szczegółowy opis, w tym linki do forum.

Wysyłanie żądania wyciągnięcia

Jeśli jesteś zadowolony ze swoich zmian w kodzie i commitów, musisz wypchnąć swoje commity na GitHub.

git push origin new_branch_name

Zmiany są prezentowane publicznie, jednak musisz zaproponować swoje zmiany do integracji w gałęzi głównej Nette. Aby to zrobić, należy złożyć pull request. Każdy pull request ma tytuł i opis. Proszę podać jakiś opisujący tytuł. Często jest on podobny do nazwy gałęzi, na przykład “Securing signals against CSRF attack”.

Opis pull request powinien zawierać jakieś bardziej szczegółowe informacje na temat zmian w Twoim kodzie:

- bug fix? yes/no   <!-- #issue numbers, if any -->
- new feature? yes/no
- BC break? yes/no
- doc PR: nette/docs#???  <!-- highly welcome, see https://nette.org/en/writing -->

Proszę zmienić tabelę informacji, aby dopasować ją do swojego pull requesta. Komentarze do każdej pozycji listy:

Mówi czy pull request dodaje feature czy jest to bugfix.
Odnosi się ewentualnie do powiązanego problemu, który zostanie zamknięty po połączeniu pull requesta.
Mówi czy pull request wymaga zmian w dokumentacji, jeśli tak, podaj referencje do odpowiednich pull requestów. Nie musisz dostarczać zmian w dokumentacji od razu, jednak pull request nie zostanie scalony, jeśli zmiany w dokumentacji są potrzebne. Zmiana dokumentacji musi być przygotowana dla dokumentacji angielskiej, inne mutacje językowe są opcjonalne.
Mówi, jeśli żądanie pociągnięcia tworzy przerwę BC. Proszę, rozważ wszystko, co zmienia publiczny interfejs jako przerwę BC.

Ostateczna tabela może wyglądać jak:

- bug fix? no
- new feature? yes   issue #123
- BC break? no

Przerabianie zmian

Otrzymywanie komentarzy do zmian w kodzie jest naprawdę częste. Proszę, spróbuj zastosować się do proponowanych zmian i przerobić swoje commit'y, aby to zrobić. Możesz popełnić proponowane zmiany jako nowe commity, a następnie zgnieść je do poprzednich. Zobacz interaktywny rozdział rebase na GitHubie. Po rebasingowaniu zmian, wymuś zmiany do swojego zdalnego widelca, wszystko zostanie automatycznie propagowane do pull request.