Инструкция по Git(Hub)

Если Вы хотите помочь в создании губки, у Вас есть какие-то дополнения к API или Вы хотите усовершенствовать наши документы, тогда вам стоит ознакомиться с git и GitHub. Если Вы уже знакомы с этим (forking, branches, issues, pull-requests и commits), просто пропустите этот раздел. Если Вы понятия не имеете, о чем идёт речь, то читайте дальше.

Примечание

В этом руководстве предполагается, что в уже ознакомились со статьёй Установка Git и уже настроили компьютер для работы с клиентом Git по вашему усмотрению.

Основная концепция Git и GitHub

Git позволяет многим разработчикам одновременно разрабатывать одну часть программного обеспечения. GitHub — это веб-сайт, на котором разработчики могут сотрудничать и обмениваться своей работой с другими пользователями. GitHub использует Git для управления указанной работой.

Совет

Если вам непонятна лексика Git или GitHub, взгляните на словарную страницу GitHub.

Repo Overview

В этом случае у репозитория SpongePowered``имеется две ветки под названием ``master и feature 1 и несколько коммитов на обеих ветках.

Давайте рассмотрим общую концепцию — начнём с репозитория. Репозиторий (от англ. repository; сокр. репо) это место, где хранятся файлы проекта. Репозитории SpongePowered хранятся на GitHub. Однако у этого репо есть ограничения доступа, для охраны его от нежелательных и вредоносных изменений. Вы не сможете самостоятельно внести изменения, так как для обычных пользователей репо доступно только для чтения. Сейчас Вы можете задаться вопросом, как же Вам вносить изменения. Для этого существуют форки (forks). Вы можете взять копию репо SpongePowered и вносить необходимые изменения там. По завершении вы можете отправить его на наш репозиторий в качестве запроса (Pull Request, PR). Предложенные вами изменения будут рассматриваться и наши сотрудники сообщат Вам об ошибках или возможности улучшения, и в конечном итоге проведёт слияние запроса (Merge Pull Request).

Ниже приведено краткое изложение описанной выше процедуры, прежде чем вдаваться в подробности:

  1. Форкнуть репозиторий на Ваш выбор
  2. Клонирование его на Ваше устройство
  3. Создание новой ветки
  4. Внесение необходимых изменений
  5. Проверка на работоспособность
  6. Фиксация изменений
  7. Синхронизация изменений на GitHub
  8. Предложение изменений на репо SpongePowered в качестве PR
  9. При необходимости внести изменения в PR
  10. Команда внедряет ваш PR в ветку master

Подробнее, пожалуйста!

1. Forking a Repo

Примечание

Этот шаг необходим при условии, что у Вас нет соответствующих прав на репозиторий, куда вы хотите внести изменения. Если это Ваш репо, то ничего форкать не нужно. Просто пропустите этот шаг и выполните clone напрямую. Если же Вы вносите изменения в репо Sponge и не состоите в команде, этот шаг необходим.

Поскольку концепция вам уже известна, мы обсудим детали. Сначала Вам нужно форкнуть репозиторий, куда вы хотите внести изменения. Это можно сделать с помощью GitHub.com, где Вы можете найти кнопку Fork вверху страницы репозитория. После её нажатия GitHub выполнит работу и предоставит Вам клон оригинального репо. Заметьте, что клон теперь находится на ВашGitHubАккаунт/НазваниеКлонированногоРепозитория. Итак, первый шаг завершен.

Примечание

Все ветки оригинального репозитория тоже будут форкнуты, это абсолютный клон форкнутого репо.

Repo forking

2. Cloning the Fork to Your local Machine

Теперь вам необходимо поместить форк на Ваше устройство для внесения изменений. Откройте, выбранный Вами клиент Git (Установка Git) и выполните clone для форкнутого репозитория. Клиент попросит вас указать папку для клонирования. Отлично, второй шаг пройден!

Примечание

Большинство действий могут быть выполнены через GUI. Если же у Вас есть опыт работы с командной строкой, то можете также ею пользоваться. В каждом из шагов будут показаны необходимые команды для достижения желаемого результата.

В качестве альтернативы вы можете пользоваться CLI (интерфейс командной строки, CMD или powershell на Windows). Обратите внимание, что до выполнения команды вам необходимо создать папку для клонирования:

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

3. Creating a New Branch

Теперь, когда у вас есть локальный клон Вашего форка, пришло время создать ветку для работы. Ветви были спроектированы таким образом, чтобы они могли одновременно разрабатывать и тестировать различные функции или дополнения, не вызывая проблем и ошибок из-за вмешательства дополнений. Настоятельно рекомендуется не вносить свои изменения в ветку master. Вместо этого создайте новую ветвь самостоятельно (с разумным именем) и внесите изменения туда.

Это означает, что нам нужно сначала создать branch (ветку), так что давайте! Вы можете сделать это через Ваш клиент (где-то должна быть кнопка create branch (создать ветку)), или вы можете использовать CLI с git:

git checkout -b [name_of_your_new_branch]

Это создаст branch с именем по вашему выбору и переключится на неё. Все изменения, которые вы собираетесь сделать, будут в этой ветке. Если вам нужно переключиться на другую ветвь (например, master), просто повторно используйте эту команду. Третий шаг сделан! Хорошая работа! Чтобы получить обзор ваших веток, просто посмотрите в своём git клиенте или воспользуйтесь CLI:

git branch
Branches

Теперь пришло время вносить изменения. Для этого можно использовать редактор или IDE, на Ваш выбор.

4. Test if Your Changes Work

Для SpongeAPI и реализаций вам нужно запустить gradle compileJava. Переходите к следующему шагу, если оно завершится без ошибок. Если этого не произойдет, внесите соответствующие исправления и повторите попытку.

Для SpongeDocs вы можете просто отправить свой PR. Он будет автоматически собран и отобразит возможные ошибки. Другой вариант — создать документацию локально. Посмотрите на Readme.md в документации для дальнейших инструкций.

5. Commit the Changes

Когда все будет готово, вам нужно объединить их в один пакет (commit (коммит)) и поместить их в ветку. Снова Ваш git-клиент поможет нам. Добавьте понятное название к вашему коммиту и краткое описание по необходимости. Это можно сделать и через CLI:

Сначала соберите все файлы и папки, которые вы хотите поместить в коммит:

git add <file>
git add <folder>

Теперь, когда файлы добавлены в список изменений, которые вы хотите включить в коммит, просто выполните

git commit

Это откроет текстовое окно, где вы можете добавить сообщение, если пожелаете. Взгляните на сообщение ниже. Вам необходимо запомнить, что ваши коммиты сохранены только локально, не на вашем форке GitHub.

Примечание

У Вас может быть несколько коммитов в PR. Просто продолжайте и изменяйте всё, что вам нужно, и фиксируйте изменения. Позже Вы сможете объединить коммиты в один.

Шестой шаг завершен. Почти закончили!

Committing

6. Sync to GitHub

Теперь нам нужно внести изменения в Ваш форк на GitHub. Все, что Вы уже сделали, сейчас храниться лишь локально. Как и всегда, вы можете использовать ваш git-клиент для этого (есть кнопка где-то в вашем GUI), или вы можете сделать это через CLI:

git push <remote> <branch>

В этом случае оно должно выглядеть так:

git push origin feature/YourFeature
Pushing commits

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

Вы можете перейти на свою страницу форка на GitHub.com (должно быть вспомогательное уведомление в верхней части страницы форка), или Вы можете использовать клиент GitHub для создания pull-request. Официальный клиент GitHub для Windows использует для этого верхний правый угол окна.

PRs

8. Amend Your PR if Necessary

Если нам необходимо внести изменения в Ваш PR, просто сделайте больше коммитов для ветки, созданной выше. Дальнейшие коммиты будут автоматически добавлены в ваш PR.

9. Your PR Gets Pulled

Ну вот, всё готово! Отличная работа!

Расширенный Git

Объединение и перемещение

Допустим, вы закончили свои дополнения к репо, и давайте представим, что вы совершили 137 коммитов. Ваша история коммитов, безусловно, будет выглядеть загроможденной. Было бы позором, если бы все они были записаны в репо, не так ли? Слишком много тривиальных коммитов также загромождает историю проекта. К счастью, у Git есть замечательный инструмент для обхода этого, он называется rebase. Rebase может взять ваши 137 небольших коммитов и просто превратить их в один большой коммит. Удивительно, не так ли? Вместо того, чтобы изобретать колесо, мы просто передадим вам ссылку на очень короткую и понятную инструкцию по сквошингу:

Gitready: Squashing with Rebase (англ.)

Это визуальное отображение того, что он делает:

Squashing commits

Настройка удалённого репозитория

Естественно, исходное репо — это прямой родитель вашей вилки, и ваша вилка является прямым родителем вашего локального клона. Однако исходное репо не является прямым родителем вашего клона. Это не проблема, но оно не позволяет Вам обновить ваш клон до последних изменений в исходном репо. Если вы настроите исходное репо как Ваш удалённый («родительский») клон, вы сможете захватить все изменения, сделанные в этом репо, и применить их к вашему локальному клону. Посмотрите ниже, чтобы узнать, как работает захват и обновление.

Setting up a remote

Хорошо. Этот шаг выполняется с помощью CLI, поскольку большинство графических интерфейсов не обладают этой (довольно продвинутой) функциональностью:

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

Если вы не уверены, работает ли это по назначению или вы хотите проверить, какие удалённые репо в настоящее время установлены, Вы можете проверить с помощью:

git remote -v

вывод должен выглядеть так:

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)

Примечание

Если вы видите предупреждение fatal: The current branch НазваниеВашейВетки has no upstream branch., тогда ветвь может не находиться на удаленном удаленном сервере. Это может произойти, если вы первый раз отправляете коммит на новую ветвь. Чтобы обновления текущей ветки и установки удалённого upstream, используйте git push --set-upstream origin НазваниеВашейВетки.

Перемещение

Допустим, Вы внесли некоторые изменения в свою желаемую ветку, но в то же время кто-то ещё обновил репо. Это означает, что Ваш форк и Ваш клон устарели. Это не большая проблема, но чтобы избежать проблем при последующем слиянии ваших дополнений, мы настоятельно рекомендуем провести rebase ваших изменений в отношении последних изменений в исходном репо. Если вы еще не настроили удалённый репозиторий, сделайте это до повторной установки.

Для успешного rebase требуется несколько шагов:

1. Fetch the Changes on the Remote Repo

Сначала вам нужно получить изменения в удалённый репозиторий. Это (снова) делается через CLI:

git fetch upstream

Это добавит все изменения с удаленного upstream и поместит их во временную ветвь upstream/master.

2. Merge Remote Changes locally

Теперь нам нужно выбрать нашу локальную ветвь master:

git checkout master

После этого мы объединим изменения, которые включены в upstream/master, в нашу локальную ветвь master:

git merge upstream/master

Хорошо, вот что у нас получилось:

Rebasing 1

3. Rebase Local Branch against Updated Master

Следующим шагом является rebase локальной ветви, с которой вы работаете, на место локальной master. Нам нужно переключиться на вашу рабочую ветвь (здесь: feature/yourfeature), а затем выполнить rebase. Это делается с помощью:

git checkout feature/yourfeature
git rebase master

Это перемотает ветку, добавит коммиты из мастера и затем снова применит ваши собственные изменения. Результат выглядит следующим образом:

Rebasing 2

4. Push Everything to your Fork

Последнее, что нам нужно сделать, это отправить всё в форк. Если вы уже создали PR, он автоматически обновится:

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

Вы сделали это, потрясающе! Отличная работа!