Współtworzenie repozytorium open source

Zakończone

Po wybraniu obszaru, w którym chcesz wnieść swój wkład, możesz przygotować swoją kontrybucję. Przedstawimy tu sposoby komunikowania swoich intencji uczestniczenia w projekcie, formowania żądania ściągnięcia i zwiększania szans zaakceptowania Twojego wkładu.

Komunikacja to kluczowy czynnik zapewniający sukces w procesie współtworzenia projektu open-source. Komunikując się z innymi osobami na temat proponowanych przez Ciebie zmian i ulepszeń, możesz czuć się niekomfortowo. Często ten dialog będzie prowadził to do dyskusji i kompromisów względem Twojej oryginalnej wizji.

Unikanie aktywnej komunikacji z innymi osobami, które są zaangażowane w projekt open-source, oznacza ryzyko poświęcenia czasu na pracę nad zadaniami, nad którymi już pracuje ktoś inny. Może też się okazać, że pracujesz nad funkcjami lub ulepszeniami, które nie są zgodne z wartościami projektu lub najlepszymi rozwiązaniami. W obu przypadkach czas wszystkich zaangażowanych osób będzie stracony. Z drugiej strony zaangażowanie w aktywną komunikację zagwarantuje, że Twoja praca zostanie dobrze odebrana i będzie miała wpływ na cały projekt.

Jak można zagwarantować sukces w komunikowaniu się z innymi członkami projektu w sprawie nowych funkcji i zmian? Po pierwsze należy zachować otwartość umysłu. Bądź otwarty na opinie i praktykuj cierpliwość. Osoby odpowiedzialne za projekt open-source najprawdopodobniej mają stałą pracę i życie prywatne. Jeśli nie otrzymasz natychmiastowej odpowiedzi, zachowaj spokój i powstrzymaj się od ponaglania innych.

Komunikowanie swoich intencji osobom odpowiedzialnym za projekt

Zanim zaczniesz wykonywać jakąkolwiek pracę, zawsze wcześniej przedstaw swój zamiar wniesienia wkładu. Najlepiej zrobić to za pośrednictwem monitora problemów, chyba że wskazano inaczej w pliku README.

• Jeśli chcesz pracować nad istniejącym problemem, sprawdź, czy nikt inny nie jest do niego przypisany, przeglądając sekcję Assignees (Osoby przypisane). Sprawdź również sekcję Linked pull requests (Połączone żądania ściągnięcia). Połączone żądanie ściągnięcia oznacza, że ktoś już pracuje nad danym problemem. Zapoznaj się z komentarzami, aby dowiedzieć się, czy ktoś nie przejawiał zainteresowania pracą nad daną kwestią. Jeśli wszystko jest jasne, zamieść komentarz dotyczący problemu, aby wskazać zainteresowanie pracą nad nim. W ten sposób mówisz ludziom, którzy mogą przyjść później, że ktoś pracuje nad problemem. Ponadto, w razie potrzeby, osoby odpowiedzialne za projekt mogą przekazać Ci wskazówki i podpowiedzi.

  

• Jeśli chcesz pracować nad nową funkcją lub usterką, o której jeszcze nie wspomniano w monitorze problemów, utwórz nowy problem. Pamiętaj, aby postępować zgodnie z szablonem problemu, jeśli został on zaproponowany, i wyraźnie wyrazić zamiar pracy nad tym problemem. Jeśli jest to propozycja nowej funkcji lub jeśli problem wymaga wprowadzenia wielu zmian, przed przejściem do następnego kroku uzyskaj zatwierdzenie ze strony osób odpowiedzialnych za projekt.

Tworzenie żądania ściągnięcia w repozytorium GitHub

Po zakomunikowaniu swojej intencji pomocy przy projekcie możesz rozpocząć pracę nad swoją kontrybucją.

Twoja kontrybucja przyjmie postać żądania ściągnięcia, czyli PR. Żądanie ściągnięcia to specjalne miejsce w witrynie GitHub, które zawiera kilka elementów:

• Tytuł i opis zmian.
• Co najmniej jedno zatwierdzenie składające się na proponowane zmiany.
• Komentarze, w których każdy może uczestniczyć w dyskusji na temat zmian.
• Przeglądy kodu, w których można znaleźć szczegółowe opinie na temat zmian i ostatecznie zatwierdzić sugestie.
• Sprawdzenia stanu pochodzące na przykład z testów automatycznych, które mogły być przeprowadzane przez osoby odpowiedzialne za projekt. Sprawdzenia stanu mogą służyć różnym celom. Mogą na przykład zapewnić, że zmiany są zgodne z regułami projektu lub że zmiany nie przerywają kodu.

Po utworzeniu żądania ściągnięcia można je aktualizować za pomocą nowych zatwierdzeń, komentarzy lub przeglądów kodu. Ten proces jest kontynuowany do momentu, gdy osoby odpowiedzialne za projekt zaakceptują i scalą żądanie ściągnięcia lub odrzucą zmiany i zamkną żądanie ściągnięcia. Scalenie żądania ściągnięcia oznacza, że Twoje zmiany zostały zintegrowane z bazą kodu projektu.

Tworzenie żądania ściągnięcia krok po kroku

1. Otwórz stronę github projektu, do którego chcesz współtworzyć.

2. Wybierz przycisk rozwidlenia, aby utworzyć kopię repozytorium na swoim koncie usługi GitHub. Ten krok jest niezbędny, ponieważ domyślnie nie masz uprawnień do wprowadzania żadnych zmian w repozytorium publicznym, chyba że jest to twoja własna kopia. Przez rozwidlenie projektu tworzysz kopię, w której możesz wprowadzać zmiany.

   

3. Wybierz pozycję Twoje repozytoria z menu profilu konta.

   

4. Wybierz rozwidlenie repozytorium.

5. Wybierz przycisk Code (Kod), aby uzyskać informacje dotyczące sposobu klonowania repozytorium Git na komputerze lokalnym.

   

6. Wybierz ikonę schowka , aby skopiować adres URL repozytorium, a następnie wprowadź w terminalu:

   git clone <REPOSITORY_URL>
   

   To polecenie spowoduje utworzenie kopii repozytorium na komputerze lokalnym.

   Alternatywnie możesz użyć programu GitHub Desktop, jeśli wolisz korzystać z aplikacji. Możesz również skorzystać z narzędzia GitHub Codespaces, jeśli ta opcja zostanie Ci zaproponowana. Jeśli jesteś użytkownikiem programu Visual Studio Code, nie będziesz mieć problemu z korzystaniem z narzędzia Codespaces.

7. Po zakończeniu klonowania projektu przejdź do folderu projektu:

   cd <PROJECT_FOLDER>
   

8. (Opcjonalnie) Utwórz nową gałąź przy użyciu następującego polecenia:

   git checkout -b <BRANCH_NAME>
   

   Ten krok nie jest obowiązkowy, ale jest zdecydowanie zalecany. Tworząc nową gałąź, możesz pracować osobno nad wieloma kontrybucjami, z których każda używa innej gałęzi.

9. Wprowadź żądane zmiany w projekcie i zatwierdź je:

   git add .
   git commit -m "<COMMIT_MESSAGE>"
   

   Te polecenia przygotują zmiany do zatwierdzenia, a następnie utworzą zatwierdzenie z określonym komunikatem. Pamiętaj o dokładnym opisaniu zmian w komunikacie dotyczącym zatwierdzania. Dobrym pomysłem jest również sprawdzenie, czy w pliku CONTRIBUTING istnieją wzmianki dotyczące konwencji zatwierdzania komunikatów, które należy przestrzegać.

10. Wypchnij zmiany do zdalnego repozytorium za pomocą następującego polecenia:

    git push --set-upstream origin <BRANCH_NAME>
    

    To polecenie tworzy nową gałąź w repozytorium nadrzędnym w witrynie GitHub (Twoje rozwidlenie) i wypycha do niej wszystkie zatwierdzenia.

    Uwaga

    Termin nadrzędne repozytorium odnosi się do repozytorium zdalnego połączonego z repozytorium lokalnym. origin to domyślny alias adresu URL repozytorium utworzonego przez usługę Git w kroku 4.

    Jeśli wcześniej nie utworzono gałęzi, wprowadź tylko git push.

11. Otwórz rozwidlenie projektu w witrynie GitHub, a następnie wybierz przycisk Compare & pull request (Porównaj i utwórz żądanie ściągnięcia) w wyświetlonym oknie sugestii.

    

12. Wypełnij tytuł i opis, a następnie wybierz pozycję Utwórz żądanie ściągnięcia.

    

    Jeśli istnieje szablon opisu żądania ściągnięcia, wprowadź do niego wszystkie wymagane informacje. Jeśli nie ma szablonu, opisz możliwie dokładnie kontekst, aby osoby odpowiedzialne za projekt zrozumiały, jakie zmiany proponujesz i jaki jest cel ich wprowadzenia. Należy również utworzyć link do odpowiedniego problemu, podając jego numer za pomocą elementu #<ISSUE_NUMBER>. Numer problemu można znaleźć obok jego tytułu.

    

Przekazywanie sprawdzeń stanu

Po utworzeniu żądania ściągnięcia u dołu może zostać wyświetlona sekcja ze sprawdzeniami stanu, która wygląda następująco:

Te sprawdzenia stanu są zautomatyzowane i skonfigurowane przez osoby odpowiedzialne za projekt. Ich zadaniem jest zapewnienie spójnej jakości projektu.

Aby żądanie ściągnięcia mogło zostać zaakceptowane, musi przejść wszystkie zautomatyzowane sprawdzenia. Jeśli którekolwiek sprawdzenie zakończy się niepowodzeniem, jak na powyższym zrzucie ekranu, wybierz przycisk Details (Szczegóły), aby dowiedzieć się więcej o niepowodzeniu i sprawdzić, co należy zrobić w celu rozwiązania problemu.

Jeśli nie masz pewności, jak postąpić z nieprawidłowym sprawdzeniem, zawsze możesz użyć komentarzy, aby poprosić o wskazówki lub o pomoc osoby odpowiedzialne za projekt.

Prośba o wskazówki dotyczące żądań ściągnięcia lub o ich przejrzenie

Może się zdarzyć, że nie będziesz mieć pewności co do słuszności wprowadzania niektórych zmian i zechcesz uzyskać opinię osób odpowiedzialnych za projekt. Najlepszą metodą, aby to zrobić, jest dodanie komentarza bezpośrednio do żądań ściągnięcia. Jeśli postrzegasz wprowadzone przez siebie zmiany jako wymagające dopracowania, możesz również utworzyć robocze żądanie ściągnięcia, dzięki czemu będziesz w stanie uzyskać wskazówki lub pomoc od innych współautorów.

Kiedy osoby odpowiedzialne za projekt otrzymają Twoje żądanie ściągnięcia, mogą odpowiedzieć na nie w konwersacji lub bezpośrednio przejrzeć dokonane przez Ciebie zmiany. Istnieje wiele możliwych wyników przeglądu żądania ściągnięcia:

• Zmiany zostały zatwierdzone. Gratulacje!
• Twoje żądanie ściągnięcia wymaga wprowadzenia pewnych zmian. Nie zniechęcaj się! Dokładnie zapoznaj się z udostępnioną opinią. Jeśli wprowadzisz żądane zmiany, jest bardzo prawdopodobne, że Twoje żądanie ściągnięcia zostanie zaakceptowane. Jeśli wypchniesz nowe zatwierdzenia do swojej gałęzi, żądanie ściągnięcia zostanie automatycznie zaktualizowane o nowe zmiany.
• Recenzent wprowadził pewne komentarze. Zazwyczaj oznacza to konieczność dokładniejszego lub bardziej przystępnego opisania wprowadzanych zmian.

Reagowanie na komentarze dotyczące żądania ściągnięcia

Pamiętaj, aby podczas wymiany informacji zawsze postępować zgodnie z zasadami opisanymi w kodeksie postępowania. Najprawdopodobniej zaakceptowanie wprowadzanych przez Ciebie zmian poprzedzi obszerna dyskusja z osobami odpowiedzialnymi za projekt lub innymi współautorami.

Udział w projekcie open-source wymaga cierpliwości. Czasami nie otrzymasz natychmiastowej opinii. Nie kontaktuj się z opiekunami prywatnie za pośrednictwem poczty e-mail, X lub innych środków, mając nadzieję uzyskać szybszą odpowiedź. Takie zachowanie jest uważane za szkodliwe. Dzięki publicznemu omawianiu problemów inni współautorzy i obserwatorzy mogą zrozumieć proces dokonywania zmian i poznać najlepsze sposoby ich wprowadzania.