Работа с Git и GitHub

В этом разделе объясняется, как сообщество может вносить код в Django с помощью запросов на вытягивание. Если вас интересует, как коммиттеры обрабатывают их, см. Код фиксации .

Ниже мы покажем, как создать запрос на вытягивание GitHub, содержащий изменения для заявки Trac #xxxxx. Создав полностью готовый пул-реквест, вы упростите работу рецензента, а это означает, что ваша работа с большей вероятностью будет объединена с 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/main:

git checkout -b ticket_xxxxx upstream/main

Флаг -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 вашего репозитория GitHub. Включите ссылку на вашу ветку.

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

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

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

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

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

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

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

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

В приведенном выше примере вы создали две фиксации, фиксацию «Фиксированный ticket_xxxxx» и фиксацию «Добавлены еще два теста».

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

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

git rebase -i HEAD~2

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

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

Вы также можете использовать опцию «редактировать» в 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/main.

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

Если есть конфликты слияния, вам нужно будет их разрешить, а затем использовать . В любой момент вы можете использовать для возврата в исходное состояние.git rebase --continuegit 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/main
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