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

This guide assumes that you’ve read Instalacja Git and that you’ve already setup your machine with a Git client of your choice.

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

All branches from the original repository will get forked too, you receive an exact clone of the forked repo.

Repo forking

2. Klonowanie Forka do twojego komputera

Now you need to get this fork to your local machine to make your changes. Open the Git Client of your choice (Instalacja Git) and clone your fork to your local machine. The client will ask you for a folder to store everything in. Second step finished, well done!

Informacja

Most steps can be done via GUI of your choice. If you’re experienced with a command line interface, then you can use it too. Each step will show you the required commands to achieve the desired result.

Alternatively, you can do this via CLI (command line interface, CMD or powershell on windows). Note that you need to create the folder everything is getting cloned to yourself before typing this command:

git clone git://github.com/YourGitHubAccount/ClonedRepoName.git
Repo cloning

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]

This will create a branch with the name of your choice and switch to it. All changes you’re about to make will be on this branch. If you need to switch to another branch (for example master), just reuse this command. Third step done! Good job so far! To get an overview of your branches, just have a look at your git client or use:

git branch
Branches

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

When you’re done, you need to bundle them into a single package (a commit) and get them into the branch. Again, your git client will help you out. Add a meaningful name to your commit and a short description if needed. This can be done via CLI too:

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. 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
Pushing commits

7. Zaproponowanie zmian w PR do SpongePowered Repo

You can either go to your forks page on GitHub.com (there should be a notice at the top of your forks page to guide you), or you can use your GitHub client to create a pull-request. The official GitHub for Win client uses the top right corner of the window for this.

PRs

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

Let’s say you have finished your additions to the repo, and let’s pretend that you made 137 commits while getting it done. Your commit history will certainly look cluttered. It would be a shame if they were all recorded into the repo, wouldn’t it? Too many trivial commits also clutters the project commit history. Fortunately, Git has a nice tool to circumvent this, it’s called a rebase. Rebasing can take your 137 small commits and just turn them into one big commit. Awesome, isn’t it? Instead of reinventing the wheel, we’ll just pass you a link to a very short and easily understandable squashing tutorial:

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.

A successful rebase requires several steps:

1. Pobierz zmiany na zdalnym repozytorium

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

Rebasing 1

3. Rebase lokalnego oddziału przeciwko zaktualizowanemu Masterowi

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

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