Перейти до змісту

Подання запиту на злиття

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

Робота з pre-commit

Під час фіксації будь-яких змін скрипт pre-commit запускається автоматично. Якщо під час фіксації виявлено якісь проблеми, це призведе до збою фіксації. У разі можливості скрипт pre-commit внесе необхідні зміни для усунення виявлених проблем. У наведеному нижче прикладі перевірка ruff виявила проблему з форматуванням коду:

(.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 автоматично вирішило проблему; отже, ви можете знову додати будь-які файли, які були змінені в результаті перевірок перед комітом, і повторно зафіксувати зміни. Однак деякі перевірки вимагатимуть внесення змін вручну. Після внесення цих змін додайте знову всі змінені файли та повторно зафіксуйте зміни.

(.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 і створіть pull-запит

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

Нижче наведено приклад того, що можна побачити на push, де URL-адреса виділена.

(.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» і виберіть гілку, з якої ви хочете надіслати свій pull request.
  • Якщо ви нещодавно додали зміни, перейдіть до репозиторію upstream, знайдіть банер над списком файлів, який вказує, що в репозиторії «нещодавно додавалися зміни», і натисніть кнопку «Порівняти та створити запит на злиття».
  • Скористайтеся командою gh pr create --web GitHub CLI, щоб відкрити у веб-браузері сторінку створення PR.

Командний інтерфейс GitHub: gh

GitHub надає GitHub CLI, що дозволяє користуватися багатьма функціями GitHub безпосередньо з терміналу за допомогою команди gh. У документації GitHub CLI ви знайдете опис усіх функцій.

gh pr create

Не використовуйте команду gh pr create без додаткових параметрів для створення вашого запиту на злиття. У проєктах BeeWare для запитів на злиття використовується шаблон, і ми вимагаємо, щоб усі внески відповідали цьому шаблону. Команда gh pr create дозволяє обійти використання цього шаблону.

Зміст запиту на злиття

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

Ваш пул-реквест повинен відповідати шаблону пул-реквесту від BeeWare. Якщо ви створили пул-реквест за допомогою веб-інтерфейсу GitHub, цей шаблон буде надано як основу для опису вашого пул-реквесту. Якщо ви випадково створили запит на злиття без використання цього шаблону, ви можете відредагувати запит, щоб додати вміст шаблону — але вміст шаблону повинен бути наданий і належним чином заповнений.

Опис PR повинен чітко відображати зміни, внесені в PR. Людина, яка не знає контексту, повинна мати змогу прочитати ваш опис і отримати відносно повне уявлення про те, чому вносяться ці зміни. Уникайте жартів, ідіом, розмовних виразів та зайвого форматування, такого як використання великих літер або надмірної пунктуації; це має бути просте пояснення того, що відбувається у вашому PR, і уникнення таких елементів робить опис більш зрозумілим для інших.

Якщо є випадки відтворення помилки або будь-які схеми тестування, які ви використовували, але які ще не включені до змін, представлених у PR, їх слід пояснити та додати до PR. Пояснення має містити інформацію про те, як їх виконати, та що потрібно зробити, щоб відтворити бажаний результат.

Якщо ваш пул-реквест вирішить проблему № 1234, вам слід включити текст Fixes #1234 в опис пул-реквесту. Це призведе до автоматичного закриття проблеми після злиття пул-реквесту. Ви можете посилатися на інші обговорення, проблеми або запити на злиття, використовуючи той самий синтаксис #1234. Ви можете посилатися на проблему в іншому репозиторії, додавши перед номером знак «-»; наприклад, python/cpython#1234 буде посиланням на проблему № 1234 у репозиторії CPython.

Інструменти на основі штучного інтелекту особливо схильні до написання розлогих і некорисних повідомлень у пул-реквестах. Якщо ви використовуєте такий інструмент для створення пул-реквесту, ви несете відповідальність за те, щоб опис пул-реквесту був лаконічним і містив лише інформацію, корисну для процесу рецензування. Наприклад, вам не потрібно включати деталі щодо «програми тестування», що описує, як запускати набір тестів, або «обґрунтування» того, чому баг потрібно виправити. Надмірно розлогі тексти запитів на злиття можуть призвести до того, що ваш запит буде закрито без рецензування, оскільки це не враховує обмежені ресурси основної команди.

Шаблон запиту на злиття для BeeWare

Шаблон pull request від BeeWare не є необов’язковим. Ми вимагаємо, щоб усі pull request відповідали цьому шаблону. Ваш pull request не буде розглянуто, якщо у ньому відсутній розділ «PR Checklist» або якщо ваші відповіді на питання, що вимагають позначки у відповідних полях, є неповними чи суперечливими. Якщо ви використовували інструмент штучного інтелекту для створення вашого запиту на злиття, ви повинні поставити відповідну галочку та вказати деталі у рядку «Assisted-by:».

Безперервна інтеграція

Безперервна інтеграція, або CI, — це процес виконання автоматизованих перевірок вашого запиту на злиття. Це може включати прості перевірки, наприклад, перевірку правильності форматування коду, а також виконання набору тестів і формування документації.

Існує безліч змін, які можуть призвести до збою CI. Загалом кажучи, ми не розглядатимемо PR, який не пройшов CI. Якщо ви створили pull-запит, а CI не пройшла, ми не почнемо його розгляд, доки він не пройде перевірку. Якщо ваші зміни призвели до збою, ви зобов'язані з'ясувати причину та вирішити проблему.

У разі невдачі CI посилання на помилки з’являться внизу сторінки PR під заголовком «Деякі перевірки не пройшли успішно». Ви побачите список перевірок, що не пройшли успішно; якщо є також перевірки, що пройшли успішно, цей список з’явиться у верхній частині списку всіх перевірок. Якщо натиснути на посилання з повідомленням про помилку, ви перейдете до журналу. Журнал часто містить усю необхідну інформацію, щоб з’ясувати причину помилки. Прочитайте журнал і спробуйте з’ясувати, чому сталася помилка, а потім зробіть усе необхідне для її усунення.

Іноді перевірка CI може завершитися невдало з причин, що не пов’язані з вашими змінами. Це може бути пов’язано з проблемою на комп’ютері, на якому виконується перевірка CI, або з нестабільністю самої перевірки. Якщо ви побачили збій і майже впевнені, що він не пов’язаний із вашими змінами, додайте відповідний коментар до вашого PR, і ми розберемося з цим.

Щоб запустити новий цикл CI, вам потрібно відправити нові зміни у свою гілку.

Якщо ви опинитеся в ситуації, коли вам потрібна допомога, щоб пройти CI, залиште коментар у PR, повідомивши нас про це, і ми зробимо все можливе, щоб допомогти.

Перевірки pre-commit та towncrier

Якщо перевірка pre-commit або towncrier завершиться невдало, це заблокує виконання більшості інших перевірок CI. Вам потрібно буде усунути відповідні проблеми, перш ніж буде виконано повний набір перевірок.

Наші ресурси CI обмежені. Важливо розуміти, що кожен раз, коли ви відправляєте зміни у гілку, запускається CI. Якщо ви плануєте внести кілька змін, краще зробити їх локально, а потім відправити всі одразу. CI буде виконуватися лише для найновішого коміту в пакеті, що дозволить мінімізувати навантаження на нашу систему CI.

Процес подання вашого PR вважається завершеним лише після того, як він пройде CI, або якщо ви надасте пояснення, чому це не відбулося.

Для того щоб ваш запит на злиття (pull request) міг бути переглянутий, можливо, знадобиться додати додатковий вміст, наприклад примітку про зміну.