diff --git a/docs/internals-pl/git-workflow.md b/docs/internals-pl/git-workflow.md new file mode 100644 index 0000000000..040a299beb --- /dev/null +++ b/docs/internals-pl/git-workflow.md @@ -0,0 +1,242 @@ +Cykl produkcyjny Git dla kontrybutorów Yii 2 +============================================ + +Zatem chcesz współtworzyć Yii? Świetnie! Aby przyspieszyć proces akceptacji Twoich modyfikacji, pamiętaj o przestrzeganiu poniższych +wskazówek. Jeśli pierwszy raz masz do czynienia z repozytorium Git lub GitHubem, zapoznaj się najpierw z +[dokumentacją pomocy GitHub](http://help.github.com/), witryną [sprawdź Gita](https://try.github.com) lub też poczytaj o +[wewnętrznym modelu danych Git](http://nfarina.com/post/9868516270/git-is-simpler). + +Przygotuj swoje środowisko deweloperskie +---------------------------------------- + +Poniższe instrukcje pomogą Ci w tworzeniu środowiska deweloperskiego dla Yii, którego możesz użyć podczas pracy nad bazowym kodem +frameworka Yii. Wykonać je należy tylko raz, przed pierwszą kontrybucją. + +### 1. [Sforkuj (zduplikuj własną wersję)](http://help.github.com/fork-a-repo/) repozytorium Yii w serwisie GitHub i sklonuj swojego forka do środowiska deweloperskiego + +``` +git clone git@github.com:TWOJA-NAZWA-UZYTKOWNIKA-GITHUB/yii2.git +``` + +Jeśli napotkasz na problemy związane z Gitem i GitHubem na systemie operacyjnym Linux lub też otrzymujesz błędy typu +"Permission Denied (publickey)" ("Odmowa dostępu (klucz publiczny)"), musisz odpowiednio +[skonfigurować instalację Gita do pracy z GitHubem](http://help.github.com/linux-set-up-git/). + +### 2. Dodaj główne repozytorium Yii jako dodatkowy zdalny git nazwany "upstream" + +Przejdź do folderu, do którego sklonowałeś Yii (zwykle "yii2") i uruchom następującą komendę: + +``` +git remote add upstream git://github.com/yiisoft/yii2.git +``` + +### 3. Przygotuj środowisko testowe + +Poniższe kroki nie są wymagane, jeśli chcesz pracować tylko nad tłumaczeniami lub dokumentacją. + +- uruchom `composer update`, aby zainstalować wymagane zależności (zakładając, że masz [composera zainstalowanego globalnie](https://getcomposer.org/doc/00-intro.md#globally)). + +> Note: Jeśli otrzymujesz błędu typu `Problem 1 The requested package bower-asset/jquery could not be found in any version, there may be a typo in the package name.` (`Problem 1 Wymagany pakiet bower-asset/jquery nie mógł być znaleziony w jakiejkolwiek wersji, być może w nazwie pakietu jest literówka.`), musisz uruchomić komendę `composer global require "fxp/composer-asset-plugin:^1.2.0"` + +- uruchom komendę `php build/build dev/app basic`, aby sklonować podstawowy szablon projektu aplikacji i zainstaluj dla niego zależności composera. + Komenda ta zainstaluje normalnie pakiety composera, ale jednocześnie podlinkuje folder yii2 do + pobranego wcześniej repozytorium, dzięki czemu otrzymasz instalację jednej instacji całego kodu na raz. + + Powtórz ten krok dla zaawansowanego szablonu projektu aplikacji, jeśli chcesz: `php build/build dev/app advanced`. + + Ta komenda służy również do aktualizacji zależności; uruchamia wewnętrznie `composer update`. + +> Note: Domyślnie repozytoria git klonowane są za pośrednictwem SSH - aby użyć zamiast tego połączenia HTTPs dodaj flagę `--useHttp` +> do komendy `build`. + +**Teraz dysponujesz już odpowiednim miejscem, aby rozpocząć hackowanie Yii 2.** + +Poniższe kroki są opcjonalne. + +### Testy jednostkowe + +Możesz uruchomić testy jednostkowe za pomocą komendy `phpunit` w głównym folderze repozytorium. +Jeśli nie posiadasz phpunit zainstalowanego globalnie, użyj zamiast tego komendy `php vendor/bin/phpunit`. + +Niektóre testy wymagają przygotowania i skonfigurowania dodatkowych baz danych. Możesz utworzyć plik `tests/data/config.local.php`, +aby nadpisać konfigurację ustawioną w `tests/data/config.php`. + +Możesz ograniczyć testy do grupy tych, nad którymi akurat pracujesz, np. aby uruchomić tylko testy walidatorów i redisa użyj +`phpunit --group=validators,redis`. Możesz zobaczyć listę dostępnych grup po wpisaniu `phpunit --list-groups`. + +### Rozszerzenia + +Aby pracować nad rozszerzeniami, musisz sklonować ich repozytoria. Stworzyliśmy komendę, która pozwoli Ci to zrobić w prosty sposób: + +``` +php build/build dev/ext +``` + +Oczywiście zamiast `` wpisz konkretną jego nazwę, np. `redis`. + +Jeśli chcesz przetestować rozszerzenie w jednym z szablonów projektów, po prostu dodaj je do pliku `composer.json` aplikacji +w zwyczajowy sposób, np. dodaj `"yiisoft/yii2-redis": "*"` do sekcji `require` w podstawowym szablonie aplikacji. +Uruchomienie `php build/build dev/app basic` zainstaluje rozszerzenie i jego zależności i utworzy symlink do folderu +`extensions/redis`, dzięki czemu możesz pracować bezpośrednio w repozytorium yii2, a nie folderze vendorowym composera. + +> Note: Również w tym przypadku pamiętaj o fladze `--useHttp`, jak to opisano powyżej. + + +Praca nad błędami i funkcjonalnościami +-------------------------------------- + +Mając przygotowane środowisko deweloperskie, jak zostało to opisane powyżej, możesz rozpocząć prace nad poprawianiem błędów +i rozwijaniem funkcjonalności. + +### 1. Upewnij się, że istnieje zgłoszony problem dotyczący kodu, który zamierzasz modyfikować, jeśli wymaga on wzmożonej pracy + +Wszystkie nowe funkcjonalności i poprawki błędów powinny być powiązane ze zgłoszeniem, aby zapewnić punkt odniesienia dla dyskusji +i komentarzy. Poświęć kilka minut, aby przejrzeć istniejące zgłoszenia i odszukać takie, które opisuje Twoją przyszłą kontrybucję. +Jeśli je znajdziesz na liście, dopisz w nim komentarz z informacją, że pracujesz aktualnie nad tym zagadnieniem. Jeśli takiego +zgłoszenia nie znajdziesz, [stwórz nowe](report-an-issue.md) lub dodaj prośbę o dołączenie kodu bezpośrednio, jeśli to prosta poprawka. +Pozwoli to zespołowi programistów zapoznać się z Twoją sugestią i zapewnić odpowiednią pomoc i komentarz w czasie całego procesu. + +> W przypadku drobnych zmian, problemów z dokumentacją czy też szybkich poprawek kodu, nie musisz zgłaszać nowego problemu; prośba o dołączenie kodu jest wystarczająca. + +### 2. Pobierz aktualny kod z głównego repozytorium Yii + +``` +git fetch upstream +``` + +Od tego kroku powinieneś zawsze zaczynać w przypadku każdej nowej kontrybucji, aby upewnić się, że pracujesz na aktualnej wersji kodu. + +### 3. Stwórz nową gałąź repozytorium dla Twojej funkcjonalności bazując na aktualnej gałęzi master Yii + +> Jest to bardzo ważne, ponieważ nie będziesz mógł wysłać więcej niż jednej prośby o dołączenie kodu z Twojego konta, jeśli będziesz +> używać gałęzi master. + +Każdy oddzielna poprawka błędu czy też zmiana kodu powinna być utworzona w swojej własnej gałęzi. Nazwy gałęzi powinny być opisowe +i zaczynać się od numeru zgłoszenia, które jej dotyczą. Jeśli nie poprawiasz któregoś z konkretnych zgłoszeń, po prostu pomiń numer. +Dla przykładu: + +``` +git checkout upstream/master +git checkout -b 999-nazwa-twojej-galezi-w-tym-miejscu +``` + +### 4. Zademonstruj swoją magię, napisz swój kod + +Upewnij się, że działa poprawnie :) + +Testy jednostkowe są zawsze mile widziane. Prawidłowo i w całości przetestowany kod znacznie upraszcza proces weryfikacji kontrybucji. +Akceptowane są również testy jednostkowe kończące się porażką jako opisy zgłoszeń problemów. + +### 5. Zaktualizuj CHANGELOG (dziennik zmian) + +Zedytuj plik CHANGELOG, aby dołączyć informację o Twojej modyfikacji; powinna ona znaleźć się na samym początku pliku zaraz +pod pierwszym nagłówkiem (określającym wersję, nad którą właśnie trwa praca). Linia w dzienniku zmian powinna być zapisana +po angielsku i wyglądać jak jedna z poniższych: + +``` +Bug #999: a description of the bug fix (Your Name) +Enh #999: a description of the enhancement (Your Name) +``` + +`#999` jest numerem zgłoszenia, do którego odnosi się `Bug` (błąd) lub `Enh` (ulepszenie). +Dziennik zmian powinien być pogrupowany według typu (`Bug`, `Enh`) i posortowany według numerów zgłoszeń. + +W przypadku drobnych zmian, np. literówek i poprawek dokumentacji, nie ma potrzeby aktualizować pliku CHANGELOG. + +### 6. Zatwierdź swoje modyfikacje + +Dodaj swoje pliki/zmiany, które chcesz zatwierdzić do [kolejki oczekujących](http://gitref.org/basic/#add) za pomocą + +``` +git add sciezka/do/mojego/pliku.php +``` + +Możesz użyć opcji `-p`, aby wybrać modyfikacje, które chcesz, aby pojawiły się w zgłoszeniu. + +Zatwierdź swoje zmiany wraz z odpowiednio opisującym je komentarzem. Upewnij się, że podałeś w nim numer zgłoszenia w postaci `#XXX`, +aby GitHub mógł automatycznie połączyć modyfikacje ze zgłoszeniem: + +``` +git commit -m "A brief description of this change which fixes #999 goes here" +``` + +### 7. Pobierz świeży kod Yii z upstream do Twojej gałęzi + +``` +git pull upstream master +``` + +Dzięki temu możesz być pewny, że posiadasz aktualny kod w Twojej gałęzi przed wysłaniem prośby o dołączenie go. +Jeśli pojawią się jakiekolwiek konflikty scalania, powinieneś je naprawić i zatwierdzić zmiany jeszcze raz. +Dzięki temu ekipa programistów Yii będzie mogła scalić Twoje zmiany z bazowym kodem za pomocą tylko jednego kliknięcia. + +### 8. Po rozwiązaniu wszystkich konfliktów, wyślij swój kod do GitHuba + +``` +git push -u origin 999-nazwa-twojej-galezi-w-tym-miejscu +``` + +Parametr `-u` spowoduje, że Twoja gałąź zostanie automatycznie wysłana i pobrana z gałęzi GitHuba. Oznacza to tyle, że następnym +razem, kiedy napiszesz `git push`, będzie wiedział, gdzie ją wysłać. Ułatwia to pracę w przypadku, gdy chcesz zatwierdzić więcej +modyfikacji w pojedynczej prośbie o dołączenie kodu. + +### 9. Otwórz [prośbę o połączenie kodu](http://help.github.com/send-pull-requests/) z upstream. + +Przejdź do swojego repozytorium na GitHubie i kliknij "Pull Request", wybierz swoją gałąź po prawej stronie i podaj dodatkowe +szczegóły w polu komentarza. Aby połączyć wysyłaną prośbę ze zgłoszeniem umieść gdziekolwiek w komentarzu `#999`, gdzie 999 jest +numerem zgłoszenia. + +> Zwróć uwagę na to, że każda prośba o dołączenie powinna zawierać kod poprawki dla pojedynczego zgłoszenia. +> W przypadku wielu niepowiązanych ze sobą modyfikacji otwórz odpowiednie zgłoszenia do każdej z nich. + +### 10. Ktoś przejrzy i oceni Twój kod + +Ktoś zerknie na Twój kod i możesz zostać poproszony o wprowadzenie kilku zmian, a jeśli tak, przejdź do kroku #6 (nie musisz +tworzyć nowego zgłoszenia, jeśli aktualne jest wciąż otwarte). W momencie, gdy Twój kod będzie zaakceptowany, zostanie scalony +z kodem głównej gałęzi i stanie się częścią następnego wydania Yii. Jeśli jednak nie uzyska on akceptacji, nie zniechęcaj się - +różni ludzie potrzebują różnych funkcjonalności i Yii nie może zapewnić ich wszystkich dla każdego. Twój kod pozostanie dostępny +na GitHubie dla osób, które będą tego potrzebować. + +### 11. Sprzątanie + +Kiedy Twój kod zostanie zaakceptowany bądź odrzucony, możesz usunąć gałęzie, na których pracowałeś z lokalnego repozytorium +i z `origin`. + +``` +git checkout master +git branch -D 999-nazwa-twojej-galezi-w-tym-miejscu +git push origin --delete 999-nazwa-twojej-galezi-w-tym-miejscu +``` + +### Note: + +W celu wczesnego wykrycia ewentualnych problemów z integracją, każde żądanie scalenia głównego kodu Yii na GitHubie jest +weryfikowane przez automatyczne testy [Travis CI](http://travis-ci.org). Ponieważ ekipa głównych programistów stara się nie +nadużywać tej usługi, [`[ci skip]`](http://about.travis-ci.org/docs/user/how-to-skip-a-build/) jest dodawane przy komentarzu +scalenia kodu, jeśli żądanie: + +* dotyczy jedynie javascript, css lub plików obrazków, +* aktualizuje dokumentację, +* modyfikuje jedynie stałe łańcuchy znaków (np. w przypadku aktualizacji tłumaczeń) + +Dzięki temu pomijane są automatyczne testy travisa dla zmian, które i tak nie są nimi pokryte. + +### Przegląd komend (dla zaawansowanych kontrybutorów) + +``` +git clone git@github.com:TWOJA-NAZWA-UZYTKOWNIKA-GITHUB/yii2.git +git remote add upstream git://github.com/yiisoft/yii2.git +``` + +``` +git fetch upstream +git checkout upstream/master +git checkout -b 999-nazwa-twojej-galezi-w-tym-miejscu + +/* pokaż swoją magię, zaktualizuj dziennik zmian, jeśli to konieczne */ + +git add sciezka/do/mojego/pliku.php +git commit -m "A brief description of this change which fixes #999 goes here" +git pull upstream master +git push -u origin 999-nazwa-twojej-galezi-w-tym-miejscu +```