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 Git 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.

Repo Overview

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:

  1. Fork repozytorium to twój wybór
  2. Sklonuj go do twojego komputera
  3. Stwórz nowy branch
  4. Dokonaj odpowiednich zmian
  5. Sprawdź, czy wszystko działa
  6. Zatwierdź zmiany
  7. Zsynchronizuj je do GitHub
  8. Zaproponuj zmiany w PR do SpongePowered Repo
  9. Zmodyfikuj PR, jeśli to konieczne
  10. Twój PR zostanie wdrożony do głównego przez personel

A teraz szczegóły!

1. Forking a 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.

Repo forking

2. Cloning the Fork to Your local Machine

Teraz musisz pobrać ten fork do twojego komputera, aby dokonać zmian. Otwórz klienta Git, którego wybrałeś (Instalacja Git) 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
Repo cloning

3. Creating a New Branch

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
Branches

Teraz nadszedł czas na Twoje zmiany. Do tego celu użyj edytora lub IDE wybranego przez Ciebie.

4. Test if Your Changes Work

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. Commit the Changes

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!

Committing

6. Sync to 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
Pushing commits

7. Propose the Changes in a PR to the 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.

PRs

8. Amend Your PR if Necessary

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. Your PR Gets Pulled

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:

Gitready: Squashing with Rebase

Oto co robi, ładnie wizualizowane:

Squashing commits

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.

Setting up a remote

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

If you see the warning fatal: The current branch YourBranchName has no upstream branch., then the branch may not be on the upstream remote. This may happen if this is the first time you are pushing a commit for the new branch. To push the current branch and set the remote as upstream, use git push --set-upstream origin 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. Fetch the Changes on the Remote Repo

Najpierw musisz pobrać zmiany do zdalnego repozytorium. Robi się to (ponownie) za pomocą interfejsu CLI:

git fetch upstream

This will add all changes from the remote upstream and put them into a temporary upstream/master branch.

2. Merge Remote Changes locally

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:

Rebasing 1

3. Rebase Local Branch against Updated Master

Next up is rebasing the local branch you’re working in against local master. We need to switch to your working branch (here: feature/yourfeature) and then perform a rebase. This is done via:

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:

Rebasing 2

4. Push Everything to your Fork

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
Rebasing 3

Zrobiłeś to, wspaniale! Dobra robota oraz dziękujemy za latanie Rebase-Air!