Работа с Git и GitHub

В этом разделе объясняется, как сообщество может внести свой вклад в код Django с помощью «запросов на вытягивание». Если вам интересно, как коммитеры обрабатывают их, см. Фиксирование кода .

Ниже мы покажем, как создать запрос на участие GitHub, содержащий изменения для билета #xxxxx Trac. Создав полностью завершенный запрос на участие, вы упростите работу рецензентам, что также увеличит вероятность интеграции вашего кода в Django.

Также можно загрузить в Trac традиционный патч, но он менее удобен для воспроизведения.

Установка Git

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

Git репозиторий Django размещен на GitHub , и мы также рекомендуем вам работать с GitHub.

После установки Git первое, что нужно сделать, это настроить свое имя и адрес электронной почты.

$ git config --global user.name "Your Real Name"
$ git config --global user.email "[email protected]"

Обратите внимание, что это user.name должно быть ваше настоящее имя, а не псевдоним GitHub. GitHub должен распознать адрес электронной почты, который вы указываете в поле user.email , поскольку он будет использоваться для связывания ваших коммитов с вашей учетной записью GitHub.

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

После того, как ваша учетная запись GitHub создана с псевдонимом «GitHub_nick» и клонируется репозиторий Django , создайте локальную копию своего клона:

git clone https://github.com/GitHub_nick/django.git

Это создаст новый каталог «django», содержащий клон вашего репозитория GitHub. Остальные команды git на этой странице необходимо запускать в клонированном каталоге, поэтому переключитесь на него сейчас:

cd django

Ваш репозиторий GitHub будет называться «origin» в Git.

Вы также должны настроить django/django как «восходящий» пульт (то есть сообщить git, что эталонный репозиторий Django был источником вашей его вилки):

git remote add upstream git@github.com:django/django.git
git fetch upstream

Аналогичным образом вы можете добавить другие пульты, например:

git remote add akaariai git@github.com:akaariai/django.git

Работа над тикетом ¶

При работе над заявкой создайте новую ветку, посвященную этой работе, и основывайте ее на upstream / master

git checkout -b ticket_xxxxx upstream/master

Опция -b создает локальную ветку. Не стесняйтесь создавать новые ветки даже для самых маленьких вещей, они для этого предназначены.

С другой стороны, если бы вы работали над исправлением в ветке 1.4, вы бы написали

git checkout -b ticket_xxxxx_1_4 upstream/stable/1.4.x

Предположим, что работа ведется на ветке ticket_xxxxx. Внесите изменения и подтвердите их фиксацией

git commit

При написании сообщения фиксации следуйте инструкциям по сообщениям фиксации, чтобы облегчить работу коммиттера. Если вам не нравится английский, попробуйте хотя бы точно описать, что делает коммит.

Если вам нужно проделать дополнительную работу в своей ветке, делайте коммит сколько угодно раз:

git commit -m 'Added two more tests for edge cases'

Публикация вашей работы

Вы можете опубликовать свою работу на GitHub, запустив

git push origin ticket_xxxxx

Когда вы перейдете на свою страницу GitHub, вы увидите, что была создана новая ветка.

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

Обратите внимание, что указанная выше ветвь называется тематической веткой на Git lingo. Вы можете переписать историю этой ветки, например, с помощью . Другие люди не должны основывать свою работу на такой ветке, так как их клон будет поврежден, когда вы внесете изменения.git rebase

Есть также государственные отделения. Это ветки, которые, вероятно, разветвятся другими людьми, поэтому их историю никогда не следует изменять. Хорошими примерами публичных веток являются ветки master и stable/A.B.x в репозитории django/django .

Когда вы думаете, что ваша работа готова к интеграции в Django, пора создать запрос на перенос в GitHub. Хороший запрос на взнос означает:

  • фиксирует каждое их логическое изменение, соблюдая стиль кода ;
  • правильно сформированные сообщения для каждой фиксации: одна итоговая строка, затем 72 абзаца строки символов - подробности см. в руководстве по фиксации ;
  • документация и тестирование при необходимости - в реальности тестирование требуется всегда, кроме изменений документации.

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

После создания запроса на участие вы должны добавить комментарий в соответствующий тикет Trac, объясняющий, что вы сделали. В частности, вы должны указать среду, в которой вы запускали тесты, например: «все тесты проходят с SQLite и MySQL».

Запросы на участие GitHub имеют только два состояния: открытое и закрытое. У разработчика, который будет обрабатывать этот запрос, есть только два варианта: объединить его или закрыть. Вот почему бесполезно создавать запрос на добавление до того, как код будет готов к слиянию или достаточно близко, чтобы разработчик с правами на фиксацию мог завершить его сам. четный.

Ребазинг веток

В приведенном выше примере вы создали две фиксации: фиксация «Fixed ticket_xxxxx» и фиксация «Добавлены еще два теста».

Мы не хотим, чтобы вся история вашего рабочего процесса была в вашем репозитории. Ваш коммит «Добавлены еще два теста» будет бесполезным шумом. Вместо этого мы бы предпочли иметь только один коммит, содержащий всю вашу работу.

Чтобы переработать историю своей ветки, вы можете объединить коммиты в одну, используя интерактивную перебазировку:

git rebase -i HEAD~2

HEAD ~ 2 выше - это сокращение для двух последних коммитов. Приведенная выше команда откроет редактор, показывающий два коммита с префиксом «выбрать».

Вместо этого замените "pick" во второй строке на "squash". Это сохранит первую фиксацию и превратит вторую фиксацию в первую. Сохраните и выйдите из редактора. Должно открыться второе окно редактора, так что теперь вы можете переформулировать сообщение фиксации для фиксации, поскольку оно включает оба ваших шага.

Вы также можете использовать опцию «редактировать» в rebase. Таким образом вы можете изменить одну фиксацию, например, чтобы исправить опечатку в строке документации:

git rebase -i HEAD~3
# Choose edit, pick, pick for the commits
# Now you are able to rework the commit (use git add normally to add changes)
# When finished, commit work with "--amend" and continue
git commit --amend
# Reword the commit message if needed
git rebase --continue
# The second and third commits should be applied.

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

git push -f origin ticket_xxxxx

Обратите внимание, что это перезапишет историю ticket_xxxxx - если вы проверите хэши фиксации до и после операции на GitHub, вы заметите, что хеши фиксации больше не совпадают. Это приемлемо, поскольку ветка является тематической, и никто не должен основывать на ней свою работу.

После изменения апстрима ¶

Когда upstream ( django/django ) изменился, вам следует перебазировать свою работу. Для этого используйте:

git fetch upstream
git rebase

Работа автоматически перебазируется с использованием ветки, которую вы разветвили, в примере с использованием upstream/master .

Команда rebase временно удаляет все ваши локальные коммиты, применяет восходящие коммиты, а затем снова применяет ваши локальные коммиты к работе.

Если есть конфликты слияния, вам нужно будет их разрешить, а затем использовать . В любой момент вы можете использовать для возврата в исходное состояние.git rebase --continue git rebase --abort

Обратите внимание, что вы хотите перебазировать восходящий поток , а не объединять восходящий поток.

Причина этого в том, что при перебазировании ваши коммиты всегда будут в верхней части работы восходящего потока, а не смешиваться с изменениями в восходящем потоке. Таким образом, ваша ветка будет содержать только коммиты, относящиеся к ее теме, что упрощает сжатие.

После просмотра

Необычно добавлять нетривиальный объем кода в ядро ​​без изменений, запрошенных рецензентами. В этом случае часто бывает хорошей идеей добавлять изменения в вашу работу как одну инкрементную фиксацию. Это позволяет рецензенту легко проверить, какие изменения вы внесли.

В этом случае внесите изменения, требуемые рецензентом. Зафиксируйте так часто, как необходимо. Перед публикацией изменений переустановите свою работу. Если вы добавите две фиксации, вы запустите:

git rebase -i HEAD~2

Сдавите вторую фиксацию в первую. Напишите сообщение о фиксации следующего содержания:

Made changes asked in review by <reviewer>

- Fixed whitespace errors in foobar
- Reworded the docstring of bar()

Наконец, верните свою работу в репозиторий GitHub. Поскольку вы не касались общедоступных коммитов во время перебазирования, вам не нужно принудительно нажимать:

git push origin ticket_xxxxx

Теперь ваш запрос на перенос также должен содержать новый коммит.

Обратите внимание, что коммиттер, вероятно, превратит фиксацию обзора в предыдущую фиксацию при фиксации кода.

Работайте над исправлением

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

git checkout -b pull_xxxxx upstream/master
curl https://github.com/django/django/pull/xxxxx.patch | git am

Это создаст новую ветку, а затем применит к ней изменения из запроса на участие. На этом этапе вы можете запустить тесты или сделать все возможное, чтобы проверить качество исправления.

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

Резюме

  • Если можете, работайте с GitHub.
  • Рекламируйте свою работу в тикете Trac, добавив ссылку на свою ветку GitHub.
  • Когда у вас есть код, который, по вашему мнению, готов, создайте «запрос на вытягивание».
  • Подготовьте свои запросы на взнос как можно лучше.
  • Применяя исправления к своей работе, используйте для объединения ваших коммитов.git rebase -i
  • Когда мастер-код восходящего потока изменился, сделайте .git fetch upstream; git rebase

Copyright ©2021 All rights reserved