Opis tego, jak wygląda proces recenzji kodu. Na co zwracać uwagę i jak sugerować zmiany? # Proces ## 1. Sprawdzenie metadanych ### Tytuł rewizji Jaki jest tytuł rewizji? Tytuł powinien być zwięzły, ale zawierać kluczowe informacje, w kolejności: 1. co się zmieniło w projekcie, 2. jakiego projektu dotyczy dana rewizja. Kolejność jest istotna, ponieważ tytuł rewizji staje się tytułem commita w repozytorium. Jeżeli najpierw w tytule commita byłaby nazwa projektu, to lista commitów wyglądałaby mało użytecznie: ``` * sealpage - lorem ipsum * sealpage - set dolomet * sealpage - foo bar ``` Lepiej jest: ``` * Lorem ipsum w sealpage * Set dolomet w sealpage * Foo bar w sealpage ``` Informacja `w sealpage` jest nadmiarowa w tytułach commitów, ale jest przydatna w tytułach rewizji, ponieważ łatwiej wtedy na liście rewizji określić, która rewizja dotyczy którego projektu gdy jest ich bardzo dużo, co nierzadko się zdarza. Dlatego informacja o nazwie projektu nie musi znaleźć się w tytule commita przy lądowaniu rewizji - można ją ręcznie usunąć przed lądowaniem. Tytuły rewizji mogą być pisane albo po polsku, albo po angielsku - zależnie od tego, jaki język jest używany do pisania tytułów commitów w danym repozytorium. Jeżeli tytuł diffa nie pasuje do tytułów commitów w repozytorium, to trzeba do zrequestować zmianę tytułu diffa (lub zrobić to samodzielnie). Jeżeli w repozytorium powiązanym z rewizją nie widać ustalonego języka tytułów diffów, to trzeba to zgłosić na forum, ustalić jedną opcję i umieścić informację o wybranej opcji w README.md danego repozytorium. Przykłady dobrych tytułów rewizji: * Komponent członków zespołu na stronie sealcode * Galeria zdjęć w sealpage Przykłady złych tytułów rewizji: * "Sealpage - galeria zdjęć" (zła kolejność informacji)

Opis tego, jak wygląda proces recenzji kodu. Na co zwracać uwagę i jak sugerować zmiany? # Proces Sprawdź kolejno następujące poniżej rzeczy. Postaraj się znaleźć jak najwięcej komentarzy i następnie zrób odpowiednio "Request changes" jeżeli rewizja wymaga zmian lub "accept", jeżeli wszystko jest OK. ⚠ **Przy pisaniu komentarzy stosuj się do [Standardów komentarzy do diffów](https://hub.sealcode.org/w/sealhub_workflow/standardy/komentarze-w-diffach/)**. ## 1. Sprawdzenie metadanych Sprawdź, czy metadane rewizji spełniają każdy z punktów [dotyczących ich standardów](https://hub.sealcode.org/w/sealhub_workflow/standardy/metadane-rewizji/). Jeżeli jakichś informacji brakuje lub jakieś informacje są nieprawidłowe, popraw je samodzielnie. Jeżeli samodzielna korekta metadanych w danym przypadku niemożliwa, bo brakuje Ci jakichś informacji, to zgłoś to w odpowiednim komentarzu. Brakujące lub błędne metadane wystarczają do tego, aby zmienić status rewizji na `request changes`, jednak wciąż trzeba sprawdzić pozostałą część rewizji. ## 2. Treść taska Przeczytaj treść taska/tasków podpiętych do danej rewizji. Zwróć uwagę, czy w komentarzach do taska zostały dokonane jakieś ustalenia i miej je w pamięci czytając kod rewizji. ## 3. Test Wykonaj instrukcje opisane w Test Planie. Czy wszystko wykonuje się poprawnie? Jeżeli nie, to zaznacz to w komentarzu do całego diffa. Być może jesteś w stanie określić, która linijka którego pliku odpowiada za niepoprawne działanie kodu? Jeżeli tak, to napisz o swoich podejrzeniach w komentarzu. Załącz wszelkie stosy błędów lub screenshoty, które mogą być pomocne autorowi/autorce taska. ## 4. Lista plików Sprawdź listę plików, które zostały utworzone/zmienione w tej rewizji. Możesz wcisnąć {key F} w widoku diffa, aby schować/pokazać pasek boczny z listą plików dotkniętych daną rewizją. Czy mają poprawne nazwy? Czy są w odpowiednich katalogach? Pamiętaj, że nazwy plików powinny czytelnie wskazywać na to, co się w danym pliku znajduje. Pliki powiązane ze sobą (np. odpowiedzialne za ten sam komponent) powinny znajdować się w osobnym, wspólnym katalogu. Czy być może któreś pliki nie są używane? Czasem różne pliki tymczasowe dostają się do kodu rewizji. Czasem można je zidentyfikować patrząc na samą listę plików, ale czasem to wychodzi dopiero po przeczytaniu kodu. ## 5. Kod Przeczytaj uważnie kod rewizji. Kod powinien być zrozumiały. Jeżeli jakiś fragment kodu jest dla ciebie niezrozumiały, to zgłoś to w komentarzu, prosząc o wytłumaczenie jego działania. Postaraj się współpracować z autorem/autorką rewizji w znajdowaniu rozwiązania tego problemu. Oto lista potencjalnych rozwiązań problemu nieczytelności kodu, w kolejności od najbardziej do najmniej preferowanych: 1. Przepisanie kodu na bardziej deklaratywny (zob. [Standardy kodu, 1.3](https://hub.sealcode.org/w/sealhub_workflow/standardy/#1-3-wyra-aj-swoj-intencj)) 2. Zmiana nazw funkcji/metod/zmiennych tak, aby były bardziej zrozumiałe (np. zamiast `i`, `j`, `n` - bardziej opisowe nazwy, jak `item`, `iterator`, `count`, itp) 3. Dodanie komentarza inline wyjaśniającego działanie kodu 4. Dodanie dokumentacji tego kodu w osobnym pliku Komentując kod możesz zaznaczyć konkretną linijkę, klikając na jej numer - wtedy komentarz będzie dotyczył tej konkretnej linijki. Możesz też zaznaczyć wiele linijek jednocześnie, aby zaznaczyć ich większą ilość. ### Standardy kodu Zapoznaj się z treścią Standardów Kodu w Sealcode: https://hub.sealcode.org/w/sealhub_workflow/standardy/ sprawdź każdą linijkę zmian w rewizji pod względem zgodności ze standardami. Na początku będzie się to wydawało upierdliwe, ale z czasem zaczniesz intuicyjnie wyłapywać pewne niedoskonałości w kodzie. ## 6. Czy nic nie zostało pominięte? Zdarzają się taski polegające np. na migracji wszystkich miejsc w kodzie z rozwiązania A na rozwiązanie B. Trzeba wtedy starannie sprawdzić, czy na pewno wszystkie miejsca w których było użyte A zostały zastąpione B. Można to zrobić za pomocą komendy [`ag`](https://github.com/ggreer/the_silver_searcher), szukając w ten sposób wszystkich wystąpień jakiegoś fragmentu z A w całym projekcie. Jeżeli zostaną jakieś nieprzemigrowane fragmenty, trzeba umieścić stosowny komentarz i zrobić "request changes" ## 7. Ponowne review Gdy autor rewizji wyśle do niej nowego diffa, sprawdź ponownie każdy zmieniony fragment kodu. Upewnij się, że autor rewizji ustosunkował się do każdego z Twoich komentarzy. Zapoznaj się z wersjami w panelu "History": {F104849, size=full} Jeżeli w miedzyczasie autor wrzucał kilka nowych wersji, możesz dodać do adresu diffa `/new` - wtedy wyświetli się porównanie najnowszej wersji rewizji z tą wersją, która była aktualna ostatnim razem, kiedy wykonywałeś/aś jakąś akcję w tej rewizji: ``` https://hub.sealcode.org/D123/new/ ```

Opis tego, jak wygląda proces recenzji kodu. Na co zwracać uwagę i jak sugerować zmiany? # Proces Sprawdź kolejno następujące poniżej rzeczy. Postaraj się znaleźć jak najwięcej komentarzy i następnie zrób odpowiednio "Request changes" jeżeli rewizja wymaga zmian lub "accept", jeżeli wszystko jest OK. ⚠ **Przy pisaniu komentarzy stosuj się do [Standardów komentarzy do diffów](https://hub.sealcode.org/w/sealhub_workflow/standardy/komentarze-w-diffach/)**. ## 1. Sprawdzenie metadanych ### Tytuł rewizjiSprawdź, czy metadane rewizji spełniają każdy z punktów [dotyczących ich standardów](https://hub.sealcode.org/w/sealhub_workflow/standardy/metadane-rewizji/). Jeżeli jakichś informacji brakuje lub jakieś informacje są nieprawidłowe, popraw je samodzielnie. Jeżeli samodzielna korekta metadanych w danym przypadku niemożliwa, bo brakuje Ci jakichś informacji, to zgłoś to w odpowiednim komentarzu. Brakujące lub błędne metadane wystarczają do tego, aby zmienić status rewizji na `request changes`, jednak wciąż trzeba sprawdzić pozostałą część rewizji. ## 2. Treść taska Jaki jest tytuł rewizji? Tytuł powinien być zwięzły,Przeczytaj treść taska/tasków podpiętych do danej rewizji. ale zawierać kluczowe informacjeZwróć uwagę, w kolejności:czy w komentarzach do taska zostały dokonane jakieś ustalenia i miej je w pamięci czytając kod rewizji. 1. co się zmieniło w projekcie, 2## 3. jakiego projektu dotyczy dana rewizja.Test Kolejność jest istotnaWykonaj instrukcje opisane w Test Planie. Czy wszystko wykonuje się poprawnie? Jeżeli nie, to zaznacz to w komentarzu do całego diffa. Być może jesteś w stanie określić, która linijka którego pliku odpowiada za niepoprawne działanie kodu? Jeżeli tak, ponieważ tytuł rewizji staje się tytułem commita w repozytoriumto napisz o swoich podejrzeniach w komentarzu. Jeżeli najpierw w tytule commita byłaby nazwa projektuZałącz wszelkie stosy błędów lub screenshoty, to lista commitów wyglądałaby mało użytecznie:które mogą być pomocne autorowi/autorce taska. ``` * sealpage - lorem ipsum * sealpage - set dolomet * sealpage - foo bar ```## 4. Lista plików Lepiej jest:Sprawdź listę plików, które zostały utworzone/zmienione w tej rewizji. Możesz wcisnąć {key F} w widoku diffa, aby schować/pokazać pasek boczny z listą plików dotkniętych daną rewizją. Czy mają poprawne nazwy? Czy są w odpowiednich katalogach? Pamiętaj, że nazwy plików powinny czytelnie wskazywać na to, co się w danym pliku znajduje. Pliki powiązane ze sobą (np. odpowiedzialne za ten sam komponent) powinny znajdować się w osobnym, wspólnym katalogu. ``` * Lorem ipsum w sealpageCzy być może któreś pliki nie są używane? Czasem różne pliki tymczasowe dostają się do kodu rewizji. Czasem można je zidentyfikować patrząc na samą listę plików, ale czasem to wychodzi dopiero po przeczytaniu kodu. ## 5. Kod Przeczytaj uważnie kod rewizji. Kod powinien być zrozumiały. Jeżeli jakiś fragment kodu jest dla ciebie niezrozumiały, to zgłoś to w komentarzu, prosząc o wytłumaczenie jego działania. Postaraj się współpracować z autorem/autorką rewizji w znajdowaniu rozwiązania tego problemu. Oto lista potencjalnych rozwiązań problemu nieczytelności kodu, w kolejności od najbardziej do najmniej preferowanych: 1. Przepisanie kodu na bardziej deklaratywny (zob. [Standardy kodu, 1.3](https://hub.sealcode.org/w/sealhub_workflow/standardy/#1-3-wyra-aj-swoj-intencj)) * Set dolomet w sealpage2. Zmiana nazw funkcji/metod/zmiennych tak, aby były bardziej zrozumiałe (np. zamiast `i`, `j`, `n` - bardziej opisowe nazwy, jak `item`, `iterator`, `count`, itp) * Foo bar w sealpage3. Dodanie komentarza inline wyjaśniającego działanie kodu ```4. Dodanie dokumentacji tego kodu w osobnym pliku Informacja `w sealpage` jest nadmiarowa w tytułach commitów, ale jest przydatna w tytułach rewizji, ponieważ łatwiej wtedy na liście rewizji określićKomentując kod możesz zaznaczyć konkretną linijkę, która rewizja dotyczy którego projektu gdy jest ich bardzo dużo,klikając na jej numer - wtedy komentarz będzie dotyczył tej konkretnej linijki. co nierzadko się zdarza.Możesz też zaznaczyć wiele linijek jednocześnie, Dlatego informacja o nazwie projektu nie musi znaleźć się w tytule commita przy lądowaniu rewizji - można ją ręcznie usunąć przed lądowaniemaby zaznaczyć ich większą ilość. Tytuły rewizji mogą być pisane albo po polsku, albo po angielsku - zależnie od tego, jaki język jest używany do pisania tytułów commitów w danym repozytorium. Jeżeli tytuł diffa nie pasuje do tytułów commitów w repozytorium, to trzeba do zrequestować zmianę tytułu diffa (lub zrobić to samodzielnie).### Standardy kodu Jeżeli w repozytorium powiązanym z rewizją nie widać ustalonego języka tytułów diffów, to trzeba to zgłosić na forum, ustalić jedną opcję i umieścić informację o wybranej opcji w README.md danego repozytorium.Zapoznaj się z treścią Standardów Kodu w Sealcode: Przykłady dobrych tytułów rewizji:https://hub.sealcode.org/w/sealhub_workflow/standardy/ * Komponent członków zespołu na stronie sealcode * Galeria zdjęć w sealpagesprawdź każdą linijkę zmian w rewizji pod względem zgodności ze standardami. Na początku będzie się to wydawało upierdliwe, ale z czasem zaczniesz intuicyjnie wyłapywać pewne niedoskonałości w kodzie. ## 6. Czy nic nie zostało pominięte? Zdarzają się taski polegające np. na migracji wszystkich miejsc w kodzie z rozwiązania A na rozwiązanie B. Trzeba wtedy starannie sprawdzić, czy na pewno wszystkie miejsca w których było użyte A zostały zastąpione B. Można to zrobić za pomocą komendy [`ag`](https://github.com/ggreer/the_silver_searcher), szukając w ten sposób wszystkich wystąpień jakiegoś fragmentu z A w całym projekcie. Jeżeli zostaną jakieś nieprzemigrowane fragmenty, trzeba umieścić stosowny komentarz i zrobić "request changes" ## 7. Ponowne review Przykłady złych tytułów rewizjiGdy autor rewizji wyśle do niej nowego diffa, sprawdź ponownie każdy zmieniony fragment kodu. Upewnij się, że autor rewizji ustosunkował się do każdego z Twoich komentarzy. Zapoznaj się z wersjami w panelu "History": * "Sealpage - galeria zdjęć" (zła kolejność informacji){F104849, size=full} Jeżeli w miedzyczasie autor wrzucał kilka nowych wersji, możesz dodać do adresu diffa `/new` - wtedy wyświetli się porównanie najnowszej wersji rewizji z tą wersją, która była aktualna ostatnim razem, kiedy wykonywałeś/aś jakąś akcję w tej rewizji: ``` https://hub.sealcode.org/D123/new/ ```