Публикация работы¶

You can publish your work on GitHub by running:

git push origin ticket_xxxxx

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

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

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

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

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

• коммиты с одним логическим изменением в каждом, следуя стилю кодирования,

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

• документация и тесты, если нужны – на самом деле тесты всегда нужны, за исключением изменений в документации.

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

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

Pull requests at GitHub have only two states: open and closed. The committer 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 committer will finish it themselves.

Перебазирование веток¶

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

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

To rework the history of your branch you can squash the commits into one by using interactive rebase:

git rebase -i HEAD~2

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

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

You can also use the «edit» option in rebase. This way you can change a single commit, for example to fix a typo in a 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.

If your topic branch is already published at GitHub, for example if you’re making minor changes to take into account a review, you will need to force-push the changes:

git push -f origin ticket_xxxxx

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

После того, как удаленная ветка изменилась¶

When upstream (django/django) has changed, you should rebase your work. To do this, use:

git fetch upstream
git rebase

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

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

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

Обратите внимание, что вы хотите перебазировать по удаленной ветке, а не замерджить в нее.

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

После проверки¶

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

In this case, do the changes required by the reviewer. Commit as often as necessary. Before publishing the changes, rebase your work. If you added two commits, you would run:

git rebase -i HEAD~2

Squash the second commit into the first. Write a commit message along the lines of:

Made changes asked in review by <reviewer>

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

Finally, push your work back to your GitHub repository. Since you didn’t touch the public commits during the rebase, you should not need to force-push:

git push origin ticket_xxxxx

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

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