Отправка запроса на извлечение¶

Теперь, когда вы зафиксировали все изменения, вы готовы отправить запрос на вытягивание. Чтобы процесс проверки прошел гладко, необходимо выполнить ряд действий.

Работа с pre-commit¶

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

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

(.venv) C:\...>git add some/interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Failed
- hook id: ruff-format
- files were modified by this hook

1 file reformatted, 488 files left unchanged

ruff check...............................................................Passed
codespell................................................................Passed

В данном случае ruff автоматически устранил проблему; поэтому вы можете повторно добавить все файлы, которые были изменены в результате проверок перед фиксацией, и повторно зафиксировать изменение. Однако некоторые проверки потребуют от вас внесения изменений вручную. После внесения этих изменений повторно добавьте все измененные файлы и повторно зафиксируйте.

macOSLinuxWindows

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) $ git add some/interesting_file.py
(.venv) $ git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

(.venv) C:\...>git add some\interesting_file.py
(.venv) C:\...>git commit -m "Minor change"
check toml...............................................................Passed
check yaml...............................................................Passed
check for case conflicts.................................................Passed
check docstring is first.................................................Passed
fix end of files.........................................................Passed
trim trailing whitespace.................................................Passed
ruff format..............................................................Passed
ruff check...............................................................Passed
codespell................................................................Passed
[bugfix e3e0f73] Minor change
1 file changed, 4 insertions(+), 2 deletions(-)

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

Отправьте свои изменения в GitHub и создайте запрос на извлечение¶

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

Ниже приведен пример того, что можно ожидать на push, с выделенным URL-адресом.

macOSLinuxWindows

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) $ git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

(.venv) C:\...>git push
Enumerating objects: 15, done.
Counting objects: 100% (15/15), done.
Delta compression using up to 24 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (8/8), 689 bytes | 689.00 KiB/s, done.
Total 8 (delta 4), reused 0 (delta 0), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (4/4), completed with 4 local objects.
remote:
remote: Create a pull request for 'fix-win11-build' on GitHub by visiting:
remote:      https://github.com/<your GitHub username>/BeeWare/pull/new/fix-win11-build
remote:
To https://github.com/<your GitHub username>/BeeWare.git
 * [new branch]      fix-win11-build -> fix-win11-build

Если вы ранее отправляли текущую ветвь в GitHub, вы не получите URL-адрес повторно. Однако есть и другие способы получить URL-адрес для создания PR:

Перейдите в репозиторий, нажмите «Pull Requests» (Запросы на извлечение), затем «New pull request» (Новый запрос на извлечение) и выберите, из какого репозитория вы хотите отправить запрос на извлечение.
Если вы недавно выполняли push, перейдите в репозиторий upstream, найдите баннер над списком файлов, который указывает, что в репозитории «были недавние push», и нажмите кнопку «Сравнить и запросить pull».
Используйте команду GitHub CLI gh pr create и заполните поля в соответствии с подсказками.
Используйте команду GitHub CLI gh pr create --web, чтобы открыть веб-браузер на странице создания PR.

Любой из этих вариантов позволит вам создать новый пулл-реквест.

CLI GitHub: gh

GitHub предоставляет GitHub CLI, который дает вам доступ ко многим функциям GitHub из вашего терминала с помощью команды gh. В документации GitHub CLI описаны все функции.

Содержание запроса на извлечение¶

Заголовок запроса на извлечение должен быть информативным, четким и лаконичным. По возможности старайтесь, чтобы он был коротким, но при необходимости допускаются и более длинные заголовки. Хороший заголовок PR должен дать человеку, не знакомому с контекстом, достаточно четкое представление о том, какая ошибка или функция реализована в вашем PR.

Описание PR должно четко отражать изменения в PR. Человек, не знакомый с контекстом, должен иметь возможность прочитать ваше описание и получить относительно полное представление о том, почему вносится данное изменение. Избегайте шуток, идиом, разговорных выражений и ненужного форматирования, такого как использование заглавных букв или чрезмерное использование знаков препинания; это должно быть прямое объяснение того, что происходит в вашем PR, и избегание этих вещей делает описание более доступным для других.

Если есть какие-либо случаи воспроизведения или какие-либо тестовые схемы, которые вы использовали, но которые еще не включены в изменения, представленные в PR, их следует объяснить и включить в PR. Объяснение должно включать в себя информацию о том, как их запускать и что делать, чтобы воспроизвести желаемый результат.

Если ваш пул-реквест решит проблему № 1234, вам следует включить текст `Fixes

1234` в описание пул-реквеста. Это приведет к автоматическому закрытию проблемы¶

при слиянии пул-реквеста. Вы можете ссылаться на другие обсуждения, проблемы или пул-реквесты, используя тот же синтаксис #1234. Вы можете ссылаться на проблему в другом репозитории, добавив перед номером префикс - например, python/cpython#1234 будет ссылаться на проблему 1234 в репозитории CPython.

Непрерывная интеграция¶

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

Существует множество изменений, которые могут привести к сбоям CI. В целом, мы не будем рассматривать PR, который не проходит CI. Если вы создаете пул-реквест и CI не проходит, мы не начнем его рассмотрение, пока он не пройдет. Если ваши изменения приводят к сбою, вы несете ответственность за выяснение причины и устранение проблемы.

Когда CI завершается с ошибкой, ссылки на ошибки отображаются внизу страницы PR под заголовком «Некоторые проверки завершились с ошибкой». Вы увидите список неудачных проверок, который будет отображаться в верхней части списка всех проверок, если есть также успешные проверки. Если вы нажмете на ссылку с ошибкой, вы перейдете к журналу. Журнал часто содержит всю информацию, необходимую для выяснения причины сбоя. Прочитайте журнал и попытайтесь выяснить, почему происходит сбой, а затем сделайте все необходимое для его устранения.

Иногда проверка CI завершается сбоем по причинам, не связанным с вашими изменениями. Это может быть связано с проблемой на компьютере, на котором выполняется проверка CI, или с нестабильностью проверки CI. Если вы заметили сбой и уверены, что он не связан с вашими изменениями, добавьте соответствующий комментарий к вашему PR, и мы рассмотрим эту проблему.

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

Если вы оказались в ситуации, когда вам нужна помощь в прохождении CI, оставьте комментарий в PR, сообщив нам об этом, и мы сделаем все возможное, чтобы помочь.

Проверки pre-commit и towncrier

Если проверка pre-commit или towncrier завершится с ошибкой, это заблокирует выполнение большинства остальных проверок CI. Вам необходимо будет устранить соответствующие проблемы, прежде чем будет запущен полный набор проверок.

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

Процесс подачи вашего PR не завершен, пока он не пройдет CI, или вы не предоставите объяснение, почему это не так.

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