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 masz już skonfigurowany swój komputer z wybranym 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 Branche z oryginalnego repozytorium będzie dostawać fork, otrzymasz dokładny klon sforkowanego repozytorium.
2. Klonowanie Forka do twojego komputera
Teraz musisz pobrać ten fork do twojego komputera, aby dokonać zmian. Otwórz klienta Git, którego wybrałeś (Instalacja Gita) i clone forka na twój komputer. Klient poprosi o folder, aby zapisać wszystko w nim. Drugi krok zakończony, dobra robota!
Informacja
Większość czynności można wykonać przez wybór w GUI. Jeżeli jesteś doświadczony z interfejsu wiersza poleceń to możesz go także użyć. Każdy krok pokaże Tobie potrzebne polecenia do osiągnięcia pożądanego rezultatu.
Alternatywnie możesz zrobić wszystko za pomocą CLI (command line interface, CMD lub powershell na Windows). Uważaj, aby przedtem utworzyć folder, gdzie wszystko będzie klonowane wpisując to polecenie:
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]
To stworzy branch``a z wybraną przez Ciebie nazwą i przełączy się na niego. Wszystkie zmiany, które masz zamiar wprowadzić będą kierowane na tego brancha. Jeśli trzeba ręcznie przełączyć do innego brancha (na przykład ``master), po prostu ponownie użyj tego polecenia. Trzeci krok gotowy! Dobra robota! Aby uzyskać omówienie brancha, wystarczy spojrzeć na twojego klienta git i użyj:
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, należy zapakować je w pojedynczy pakiet (commit) i przesłać go do Brancha. Ponownie pomoże Tobie twój klient Git. Dodaj nazwę Twojego commit i krótki opis w razie potrzeby. Można to zrobić także za pomocą CMD:
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
Zarówno możesz wejść na stronę twojego forka przez GitHub.com (powinno być powiadomienie w górnej części strony twojego forka), lub można użyć GitHub, aby utworzyć Pull-Request. Oficjalny GitHub dla klienta Windows używa do tego okna w prawnym górnym 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 wzbogacenia do repo, i załóżmy że zaangażowałeś się 137 razy zanim to skończyłeś. Historia twojego zaangażowania z pewnością będzie w bałaganie. Byłoby wstyd, jeśli wszystkie zostałyby odnotowane w repo, prawda? Zbyt wiele błachych zaangażowań zaśmieca historię zmian projektu. Na szczęście Git posiada wspaniałe narzędzie do ominięcia tego, nazywa się „Rebase”. Rebazowanie może wziąć twoje 137 małych zaangażowań i przemienić je w duże. Niesamowite, nieprawdaż? Zamiast odkrywać koło na nowo, możemy po prostu podać ci link do szybkiego i łatwego do zrozumienia samouczka:
Oto co robi, ładnie wizualizowane:
Konfigurowanie pilota zdalnego sterowania
Naturally the original repo is the direct parent of your fork and your fork is the direct parent of your local clone. However the original repo isn’t the direct parent of your clone. This isn’t a problem in the first place, but it prevents you from updating your clone to the latest changes on the original repo. If you setup the original repo as a remote (read: „parent”) of your clone, you’ll be able to grab all changes made to this repo and apply it to your local clone. Look below to see how grabbing and updating works.
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.
Udana rebase wymaga kilka 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!
