mirror of
https://github.com/yiisoft/yii2.git
synced 2025-11-04 14:46:19 +08:00
Merge pull request #12303 from bizley/patch-1
internals PL git workflow
This commit is contained in:
Dmitry Naumenko
242
docs/internals-pl/git-workflow.md
Normal file
242
docs/internals-pl/git-workflow.md
Normal file
@ -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 <span id="prepare-the-test-environment"></span>
|
||||
|
||||
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 <nazwa-rozszerzenia>
|
||||
```
|
||||
|
||||
Oczywiście zamiast `<nazwa-rozszerzenia>` 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
|
||||
```
|
||||
Reference in New Issue
Block a user