Praca z Git(Hub)
Jeśli chcesz pomóc w tworzeniu Sponge, masz niesamowity dodatek do API, lub chcesz poprawnić nasze dokumenty, to musisz zapoznać się z git oraz GitHub. Jeśli jesteś już obeznany z forkiem, branch, issues, pull-requestami i commitsami to możesz pominąć ten temat. Jeżeli nie masz pojęcia o czym piszemy to czytaj dalej.
Informacja
Ten przewodnik zakłada, że przeczytałeś Instalacja Gita i że już ustawiłeś swój komputer z wybranym przez siebie klientem Git.
Podstawowa koncepcja Git i GitHub
Git pozwala wielu różnym programistom do opracowania jednego kawałka oprogramowania w tym samym czasie. GitHub jest na stronie internetowej, gdzie Deweloperzy mogą współpracować i dzielić się swoją pracą z innymi. GitHub opiera się na zarządzaniu współpracą Git.
Wskazówka
Jeżeli nie jesteś jeszcze zaznajomiony ze słownictwem Git oraz GitHub, to możesz zapoznać się z wprowadzeniem do Terminy robocze i Pobierzne w GitHub.
W tym przypadku repozytorium jest nazwane SpongePowered, posiada one dwa Branche o nazwach master i feature 1 i również mają commity obu branchy.
Pora umieścić te warunki w kontekście - począwszy od repozytorium. Repozytorium (w skrócie:repo) To miejsce, w którym projekt przechowuje swoje pliki. Repozytoria SpongePowered znajdują się na GitHub. To repozytorium ma jednak pewne ograniczenia dostępu do zabezpieczenia go od niechcianych i szkodliwych zmian. Nie można po prostu zmienić samowolnie, repo jest tylko do odczytu dla zwykłych użytkowników. Teraz można się zastanawiać na temat propozycji i zmian. Tak więc tutaj forki wchodzą w gre. Możesz pobrać kopię z repo SpongePowered i dokonać zmian. Kiedy skończysz, możesz otworzyć go jako żądanie replikacji ściągniętej (Pull-Request = PR) na nasze repozytorium. Twoje propozycje uzupełnień i zmiany teraz mogą być przeglądane, a personel powie Tobie jeżeli coś jest źle, lub wymaga poprawy i ostatecznie zostanie scalone do PR.
Krótkie podsumowanie procedury opisanej powyżej, zanim przejdziemy do szczegółów:
Fork repozytorium to twój wybór
Sklonuj go do twojego komputera
Stwórz nowy branch
Dokonaj odpowiednich zmian
Sprawdź, czy wszystko działa
Zatwierdź zmiany
Zsynchronizuj je do GitHub
Zaproponuj zmiany w PR do SpongePowered Repo
Zmodyfikuj PR, jeśli to konieczne
Twój PR zostanie wdrożony do głównego przez personel
A teraz szczegóły!
1. Zforkuj Repo
Informacja
Ten krok jest wymagany, jeżeli nie masz prawa Push do stworzenia zmian w Repo. Jeżeli pracujesz na swoim własnym repo, fork nie jest wymagany. Po prostu pomiń ten krok i clone bezpośrednio. Podczas wprowadzania zmian do Sponge i jeżeli nie jesteś pracownikiem, ten krok jest wymagany.
Teraz, gdy znasz podstawowe pojęcia to możemy omówić szczegóły. Najpierw musisz sforkować repozytorium jakie chcesz zmiany. Można to zrobić na GitHub.com, gdzie znajdziesz przycisk fork w górnej części strony repozytoriów. Po wciśnięciu go GitHub rozpocznie prace, a następnie przedstawi Tobie klon oryginalnego repo. Zauważysz, że klon znajduje się teraz w TwojeGitHubKonto/SkolonowanaRepoNazwa. Wszystko proste, pierwszy krok zakończony.
Informacja
Wszystkie gałęzie z oryginalnego repozytorium również zostaną sforkowane, otrzymasz dokładny klon sforkowanego repozytorium.
2. Klonowanie Forka do twojego komputera
Teraz musisz dostać ten fork do lokalnej maszyny, aby wprowadzić zmiany. Otwórz wybranego przez Ciebie klienta Git (Instalacja Gita) i clone fork na swoją lokalną maszynę. Klient poprosi Cię o folder do przechowywania wszystkiego. Drugi krok zakończony, dobrze!
Informacja
Większość kroków można wykonać za pomocą wybranego interfejsu GUI. Jeśli masz doświadczenie w interfejsie wiersza poleceń, możesz także z niego korzystać. Każdy krok pokaże Ci wymagane polecenia, aby osiągnąć pożądany wynik.
Alternatywnie, możesz to zrobić za pomocą CLI (interfejsu wiersza poleceń, CMD lub powershell w oknie). Zauważ, że musisz utworzyć folder, który zostanie sklonowany do siebie przed wpisaniem tej komendy:
git clone git://github.com/YourGitHubAccount/ClonedRepoName.git
3. Tworzenie nowego Branch-a
Teraz już masz lokalnego klona twojego forka, nadszedł czas na stworzenie brancha do pracy nad nim. Branche zostały zaprojektowane tak, aby móc rozwijać i testować różne funkcje lub dodatki w tym samym czasie nie powodując problemów i błędów z powodu zakłócenia dodatkami. Zaleca się nie dokonywać zmian na master branchu. Zamiast tego utwórz nowego brancha (z rozsądną nazwą) i wprowadź zmiany.
Oznacza to, że musisz stworzyć pierwszego branch. Więc zacznijmy! Można to zrobić za pośrednictwem klienta (powinien znajdować się gdzieś przycisk create branch) lub za pomocą CMD z Git:
git checkout -b [name_of_your_new_branch]
Spowoduje to utworzenie branch o wybranej nazwie i przełączenie na nią. Wszystkie zmiany, które zamierzasz wprowadzić będą na tej gałęzi. Jeśli chcesz przełączyć się na inną gałąź (na przykład master), po prostu użyj ponownie tego polecenia. Trzeci krok wykonano! Dobra robota! Aby uzyskać przegląd swoich oddziałów, wystarczy spojrzeć na swojego klienta git lub użyć:
git branch
Teraz nadszedł czas na Twoje zmiany. Do tego celu użyj edytora lub IDE wybranego przez Ciebie.
4. Sprawdź, czy twoje zmiany działają
Dla SpongeAPI i implementacji musisz uruchomić gradle compileJava. Przejdź do następnego kroku, jeśli zakończy się bez błędów. Jeżeli nie, wprowadź odpowiednie poprawki i spróbuj ponownie.
Dla SpongeDocs, możesz po prostu przesłać swój PR. Zostanie zbudowany automatycznie i pokaże ewentualne błędy. Innym rozwiązaniem jest zbudowanie Docs lokalnie. Spójrz na Readme.md w Docs aby uzyskać dalsze instrukcje.
5. Zatwierdzanie zmian
Kiedy skończysz, musisz połączyć je w jeden pakiet (commit) i dostać je do gałęzi. Ponownie Twój klient git pomoże Ci to zrobić. Dodaj miarodajną nazwę do swojego zatwierdzenia i w razie potrzeby krótki opis. Można to również zrobić poprzez CLI:
Pierw dodaj wszystkie pliki i foldery, które chcesz umieścić w commit:
git add <file>
git add <folder>
Teraz, gdy pliki zostały dodane do twojej listy zmian i zostaną dodane, po prostu wpis:
git commit
Otworzy to okno tekstowe, gdzie będziesz mógł dodać wiadomość tekstową, jeśli zajdzie taka potrzeba. Spójrz na obrazek poniżej. Zauważysz, że commit wciąż jest przechowywany lokalnie, a nie na forku w GitHub.
Informacja
Możesz mieć wiele commit-ów w PR. Po prostu idź do przodu i zmieniaj wszystko czego potrzebujesz, następnie zatwierdź zmiany. Można później scalić commit-a w jeden.
Tak więc, szósty krok jest zrobiony. Prawie gotowe!
6. Synchronizacja z GitHub
Teraz musimy przesłać zmiany do twojego forka na GitHub. Wszystko co zrobiłeś do tej pory jest przechowywane tylko lokalnie. Jak zawsze można użyć klienta Git do tego (posiada on gdzieś przycisk w Twoim GUI), lub możesz zrobić to za pomocą CMD:
git push <remote> <branch>
W tym przypadku powinno być:
git push origin feature/YourFeature
7. Zaproponowanie zmian w PR do SpongePowered Repo
Możesz przejść na stronę forków na GitHub.com (powinien być zapowiedź na górze strony forków, aby Cię poprowadzić), albo możesz użyć swojego klienta GitHub do utworzenia pull-requesta. Oficjalny GitHub dla klienta Win używa w tym celu górnego prawego rogu.
8. Popraw swój PR, jeśli to konieczne
Jeżeli chcesz wprowadzić zmiany do twojego PR to po prostu stwórz więcej commit-ów do brancha. Następny commit będzie dodany do twojego PR automatycznie.
9. Twoje PR zostaje wyciągnięte
To tyle. Jesteśmy gotowi! Świetna robota!
Zaawansowany Git
Zgniatanie z Rebase
Powiedzmy, że zakończyłeś swoje dodatki do repozytorium i udajmy, że złożyłeś 137 commitów podczas jego realizacji. Historia Twojego zobowiązania z pewnością będzie niezrozumiała. Byłoby wstyd, gdyby wszystkie zostały zapisane w repozytorium, nieprawdaż? Zbyt wiele trywialnych commitów również zaśmieca historię projektu. Na szczęście Git ma ładne narzędzie do ominięcia tego, nazywa się rebase. Rezygnacja może wziąć twoje 137 małych commitów i po prostu zamienić je w jedno wielkie zobowiązanie. Świetnie, prawda? Zamiast wynaleźć koło, przekażemy ci tylko link do bardzo krótkiego i łatwo zrozumiałego tutorialu do squashingu:
Oto co robi, ładnie wizualizowane:
Konfigurowanie pilota zdalnego sterowania
Oczywiście oryginalne repozytorium jest bezpośrednim rodzicem Twojego forka, a Twój fork jest bezpośrednim rodzicem Twojego lokalnego klonu. Jednak oryginalne repozytorium nie jest bezpośrednim rodzicem Twojego klonu. To nie jest problem w pierwszej kolejności, ale uniemożliwia Ci to aktualizację klonu do najnowszych zmian na oryginalnym repozytorium. Jeśli ustawisz oryginalne repozytorium jako pilot (przeczytaj „rodzic”) swojego klonu, będziesz mógł przechwycić wszystkie zmiany wprowadzone do tego repozytorium i zastosować je do lokalnego klonu. Spójrz poniżej, aby zobaczyć, jak działa grabbing i aktualizacja.
W porządku. Ten etap jest wykonywany przez CLI ponieważ większość GUI brakuje tej (raczej zaawansowanej) funkcjonalności:
git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git
Jeśli nie jesteś pewien że to zadziałało jako zamierzone lub jeśli chcesz sprawdzić jakie piloty są obecnie ustawione, możesz to sprawdzić przez:
git remote -v
wydajność powinna wyglądać jak:
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (fetch)
origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push)
upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (fetch)
upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git (push)
Informacja
Jeśli widzisz ostrzeżenie fatal: Bieżąca gałąź YourBranchName nie ma gałęzi w górnym biegu. Może się to zdarzyć, jeśli po raz pierwszy pychasz commita do nowej gałęzi. Aby wypchnąć bieżącą gałąź i ustawić pilota jako upstream, użyj ``git push --set-upstream pochodzenia YourBranchName.
Przerzucanie
Powiedzmy, że wprowadziłeś pewne zmiany do wybranej części repozytorium, ale w międzyczasie ktoś inny zaktualizował repozytorium. Oznacza to, że twoja kopia repozytorium i twój klon są przestarzałe. Nie jest to duży problem, ale aby uniknąć problemów podczas łączenia dodatków w późniejszym czasie, zaleca się `` zmianę bazy`` w stosunku do najnowszych zmian na oryginalnym repo. Jeśli jeszcze nie skonfigurowałeś zdalnego repo, zrób to przed próbą ponownego utworzenia bazy.
Pomyślna rebaza wymaga kilku kroków:
1. Pobierz zmiany na zdalnym repozytorium
Najpierw musisz pobrać zmiany do zdalnego repozytorium. Robi się to (ponownie) za pomocą interfejsu CLI:
git fetch upstream
Spowoduje to dodanie wszystkich zmian ze zdalnego upstream i umieszczenie ich w tymczasowej gałęzi upstream/master.
2. Scal lokalnie ręczne zmiany
Teraz musimy wybrać nasz lokalny oddział master:
git checkout master
Po tym możemy scalić zmiany, które są zawarte w „pod prąd/master`` do naszych lokalnych gałęzi master:
git merge upstream/master
Dobrze, to jest to co zrobiliśmy do tej pory:
3. Rebase lokalnego oddziału przeciwko zaktualizowanemu Masterowi
Następnym przejściem jest przekształcenie lokalnej gałęzi w którą pracujesz przeciwko lokalnym master. Musimy przełączyć się do Twojej działającej gałęzi (tutaj: feature/yourfeature), a następnie wykonać rebasę. Wykonuje się to poprzez:
git checkout feature/yourfeature
git rebase master
To cofnie twój oddział, dodaj rewizje od wzorca, a następnie zastosuj własne zmiany ponownie. Wynik wygląda następująco:
4. Wciśnij wszystko na swój widelec
Ostatnią rzeczą jaką musimy zrobić jest wciśnięcie wszystkiego na widelec. Jeśli utworzyłeś już PR, zostanie on automatycznie zaktualizowany:
git checkout master
git push -f
git checkout feature/yourfeature
git push -f
Zrobiłeś to, wspaniale! Dobra robota oraz dziękujemy za latanie Rebase-Air!
