Работа с Git и GitHub¶

Издательская деятельность¶

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

git push origin ticket_xxxxx

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

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

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

There are also «public branches». These are branches other people are supposed to fork, so the history of these branches should never change. Good examples of public branches are the main and stable/A.B.x branches in the django/django repository.

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

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

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

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

Pull requests at GitHub have only two states: open and closed. The merger who will deal with your pull request has only two options: merge it or close it. For this reason, it isn’t useful to make a pull request until the code is ready for merging – or sufficiently close that a merger will finish it themselves.

Перераспределение ветвей¶

В приведенном выше примере вы создали два коммита, коммит «Fixed ticket_xxxxx» и коммит «Added two more tests».

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

Чтобы переработать историю вашей ветки, вы можете объединить все коммиты в один с помощью интерактивного rebase:

git rebase -i HEAD~2

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

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

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

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, вы заметите, что хэши коммитов больше не совпадают. Это допустимо, так как ветка является тематической, и никто не должен основывать на ней свою работу.

После изменения восходящего потока¶

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

git fetch upstream
git rebase upstream/main

The work is automatically rebased using the branch you forked on, in the example case using upstream/main.

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

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

Обратите внимание, что вы хотите базироваться на upstream, а не сливаться с upstream.

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

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

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

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

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

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

Note that the merger is likely to squash the review commit into the previous commit when committing the code.