How to Git(Hub)

If you want to assist in creating Sponge, you have an awesome addition to the API, or you want to improve our Docs, then you’ll need to become familiar with git and GitHub. If you’re already familiar with forking, branches, issues, pull-requests and commits, then just skip this topic. If you have no clue what we’re talking about, then read on.

Примітка

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

The Basic Concept of Git and GitHub

Git allows many different developers to develop a single piece of software at the same time. GitHub is a website where developers can collaborate and share their work with others. GitHub relies on Git for the management of said work.

Порада

If you’re unfamiliar with the Git and GitHub vocabulary, have a look at the glossary page on GitHub.

Repo Overview

In this case the repo is named SpongePowered, has two branches named master and feature 1 and also some commits on both branches.

Let’s put these terms into context - beginning with the repository. The repository (short: repo) is the place where a project stores its files. The SpongePowered repositories are located at GitHub. However, this repo has some access restrictions to preserve it from unwanted or malicious changes. You can’t simply make changes yourself, as the repo is read-only for regular users. Now you may wonder how you’re supposed to file proposals and changes. Well, that’s where forks come into play. You can grab a copy of the SpongePowered repos, and make your changes there. When you’re done, you open it as a pull request (PR) on our repository. Your proposed additions and changes can then be reviewed, and staff will tell you if something is wrong, or needs improvement, and eventually merge the final PR.

Here’s a short summary of the procedure described above, before we go into detail:

  1. Fork the repo of your choice

  2. Clone it to your local machine

  3. Create a new branch

  4. Make the desired changes

  5. Test if everything works

  6. Commit the changes

  7. Sync them to GitHub

  8. Propose the changes in a PR to the SpongePowered Repo

  9. Amend to your PR if necessary

  10. Your PR gets pulled into master by staff

Details please!

1. Forking a Repo

Примітка

This step is only required if you don’t have push rights on the repo you’re making changes to. If you’re working on your own repo, no fork is required. Just skip this step and clone directly. If you’re making changes to Sponge and you aren’t staff, this step is required.

Now that you know the basic concept, we’ll discuss the details. First you need to fork the repository you want to make changes to. This can be done on GitHub.com, where you’ll find a Fork button at the top of the repositories page. After pressing it, GitHub will do some work and present a clone of the original repo to you. You’ll notice that the clone is now located at YourGitHubAccount/ClonedRepoName. Alright, first step completed.

Примітка

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

Repo forking

2. Cloning the Fork to Your local Machine

Now you need to get this fork to your local machine to make your changes. Open the Git Client of your choice (Installing 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!

Примітка

Більшість кроків можна зробити за допомогою графічного інтерфейсу за вашим вибором. Якщо у вас є досвід роботи з інтерфейсом командного рядка, ви також можете його використовувати. Кожен крок показуватиме вам необхідні команди для досягнення бажаного результату.

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. Creating a New Branch

Тепер, коли у вас є місцевий клон вашого форку, прийшов час створити гілку, над якою ви будете працювати. Гілки були спроектовані таким чином, щоб мати можливість розробляти та тестувати різні функції або додатки одночасно, не викликаючи проблеми та помилки через втручання з боку додатків. Ми наполегливо рекомендуємо вам не вносити зміни до головної гілки розробки. Замість цього створіть собі нову гілку (з розумною назвою) і робіть зміни там.

Це означає, що спочатку вам потрібно створити гілку, отже, до справи! Ви можете зробити це за допомогою вашого клієнта (там десь повинна бути кнопка створити гілку), або ви можете використовувати інтерфейс командного рядка з системою зберігання коду та контролю версій» git»:

git checkout -b [name_of_your_new_branch]

Це створить гілку з назвою по вашому вибору та переключиться на неї. Усі зміни, які ви збираєтеся зробити, будуть в цій гілці. Якщо вам потрібно переключитися на іншу гілку (наприклад, на головну), просто використовуйте цю команду. Третій крок виконаний! Добре попрацювали! Щоб отримати огляд своїх гілок, зазирніть до свого git-клієнта або сценарію:

git branch
Branches

Now it’s time to make your changes. Use the editor or IDE of your choice to do this.

4. Test if Your Changes Work

For SpongeAPI and the implementations you have to run gradle compileJava. Proceed to the next step if it finishes without errors. If it doesn’t, make the appropriate corrections and try again.

Для SpongeDocs ви можете просто надіслати свій реєстр програм. Він буде побудований автоматично і виявить можливі помилки. Інший варіант – створити Docs локально. Ознайомтеся з розділом Readme.md у Docs <https://github.com/SpongePowered/SpongeDocs/blob/master/README.md> _ для подальших інструкцій.

5. Commit the Changes

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:

First collect all files and folders you want to put into a commit:

git add <file>
git add <folder>

Now that the files are added to your list of changes you want included in the commit, just do

git commit

It will open a text window, where you can add a message if you desire. Have a look at the image below. You’ll notice that your commits are still stored locally only and not on your fork on GitHub.

Примітка

Ви можете мати декілька підтверджень у реєстрі програм. Крокуйте вперед, змініть все, що вам потрібно, та підтвердіть зміни. Ви можете об’єднати багато підтверджень в єдине пізніше.

So now, the sixth step is done. Almost there!

Committing

6. Sync to GitHub

Тепер нам потрібно зробити зміни у вашому форку на GitHub. Все, що ви зробили до цих пір, зберігається, на даний момент, лише локально. Як завжди, ви можете скористатись своїм git-клієнтом (десь у вашому графічному інтерфейсі є відповідна кнопка), або це можна зробити за допомогою інтерфейсу командного рядка:

git push <remote> <branch>

In this case it should be:

git push origin feature/YourFeature
Pushing commits

7. Propose the Changes in a PR to the SpongePowered Repo

Ви можете або перейти на сторінку ваших форків на GitHub.com (у верхній частині вашої сторінки форків має бути примітка, яка вас скерує), або скористатись своїм клієнтом GitHub, щоб створити запит на долучення коду. Для цього офіційний GitHub для Win клієнта використовує верхній правий кут вікна.

PRs

8. Amend Your PR if Necessary

If we want you to make changes to your PR, then just make more commits to the branch created above. Further commits will be added to your PR automatically.

9. Your PR Gets Pulled

That’s it. We’re all set! Great job!

Advanced Git

Squashing with Rebase

Припустимо, що ви закінчили свої доповнення до репо, і уявімо, що ви зробили 137 підтверджень, поки робили це. Ваша історія підтверджень, безсумнівно, виглядатиме захаращено. Було б соромно, якщо вони всі будуть записані в репо, чи не так? Забагато тривіальних підтверджень також засмічує історію підтверджень всього проекту. На щастя, у Gіt є хороший інструмент, щоб обійти це, він називається ребаза. Ребазування може взяти 137 ваших маленьких підтверджень і просто перетворити їх на одну велику фіксацію. Чудово, чи не так? Замість того, щоб зайвий раз винаходити колесо, ми просто передамо вам посилання на дуже короткий і зрозумілий навчальний посібник:

Gitready: Squashing with Rebase

This is what it does, nicely visualized:

Squashing commits

Setting Up a Remote

Зазвичай оригінальний репо - це безпосередній батько вашого форку, а ваш форк є безпосереднім батьком вашого місцевого клону. Однак оригінальний репо не є безпосереднім батьком вашого клону. Це не є першочерговою проблемою, але це не дозволяє вам оновлювати клон до останніх змін на оригінальному репо. Якщо ви встановите оригінальний репо як пульт управління (читай: «батько») вашого клону, ви зможете охопити всі зміни, внесені в цей репо, та застосувати їх до вашого місцевого клону. Дивіться нижче, як працює це охоплення та оновлення.

Setting up a remote

Alright. This step is done through CLI as most GUIs are missing this (rather advanced) functionality:

git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git

If you’re unsure if that worked as intended or if you want to check which remotes are currently set, you can check via:

git remote -v

the output should look like:

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)

Примітка

Якщо ви бачите попередження фатально: поточна гілка НазваВашоїГілки не має гілки верхнього потоку, тоді гілка може не знаходитися на пульті верхнього потоку. Це може статися, якщо ви вперше робите підтвердження для нової гілки. Щоб підштовхнути поточну гілку і встановити пульт як пульт верхнього потоку, використовуйте git push --set-upstream origin НазваВашоїГілки.

Rebasing

Припустимо, ви внесли деякі зміни до потрібної гілки, але тим часом хтось інший оновив репо. Це означає, що ваш форк та ваш клон застаріли. Це не велика проблема, але щоб уникнути проблем при подальшому злитті ваших доповнень, наполегливо рекомендуємо ребазувати ваші зміни проти останніх змін на оригінальному репо. Якщо ви ще не встановили віддалене репо, зробіть це перед ребазуванням.

A successfull rebase requires several steps:

1. Fetch the Changes on the Remote Repo

First you need to fetch the changes on the remote repository. This is (again) done via 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

Now we need to select our local master branch:

git checkout master

After that we’ll merge the changes that are included in upstream/master into our local master branch:

git merge upstream/master

Alright, this is what we’ve done so far:

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

This will rewind your branch, add the commits from master and then apply your own changes again. The result looks like this:

Rebasing 2

4. Push Everything to your Fork

The last thing we need to do is to push everything to the fork. If you’ve already created a PR, it will get updated automatically:

git checkout master
git push -f
git checkout feature/yourfeature
git push -f
Rebasing 3

You made it, awesome! Good job and well done and thanks for flying Rebase-Air!