Впровадження нової функції

Після завершення процесу подання пропозицій у вас має бути готовий повний проект нової функції. Це означає, що настав час приступити до написання коду!

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

Важливою складовою впровадження нової функції є забезпечення її повної документації. Як мінімум, це означає наявність документації до API; однак може також знадобитися додати посібник із використання або тематичний довідник.

Додавання нових функцій

Налаштування середовища розробки

Налаштування середовища розробки

Етапи налаштування середовища розробки залежать від проекту, до якого ви долучаєтеся. Оберіть один із наведених нижче варіантів:

• Портфель
• щодо цього
• Rubicon Objective-C

Якщо репозиторій, до якого ви хочете долучитися, відсутній у цьому списку, дотримуйтесь інструкцій з розробки для відповідного проєкту. Наприклад, якщо ви хочете працювати над репозиторієм шаблонів Briefcase, вам слід дотримуватися інструкцій для Briefcase.

Робота з гілки

Працюйте з функціональної гілки, а не з вашої гілки main

Перш ніж приступити до внесення змін, переконайтеся, що ви створили гілку. За замовчуванням під час клонування форку репозиторію ви потрапляєте на гілку main. Це пряма копія гілки BeeWare репозиторію main.

Хоча ви можете надіслати запит на злиття з вашої гілки main, краще цього не робити. Якщо ви надішлете запит на злиття, який є майже правильним, член основної команди, який перевірятиме ваш запит, зможе внести необхідні зміни, замість того щоб залишати відгук із проханням про незначні виправлення. Однак, якщо ви надішлете запит на злиття з вашої гілки main, рецензенти не зможуть вносити зміни.

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

Натомість вам слід вносити зміни у гілці функціональних оновлень. Гілка функціональних оновлень має просту назву, яка дозволяє ідентифікувати внесені вами зміни. Наприклад, якщо ви виправляєте помилку, яка спричиняє проблеми зі збіркою в Windows 11, ви можете створити гілку функцій fix-win11-build. Якщо ваша помилка пов’язана з конкретною проблемою, про яку вже повідомлено, також прийнято вказувати номер цієї проблеми в назві гілки (наприклад, fix-1234).

Щоб створити гілку функції fix-win11-build, виконайте наступну команду:

macOSLinuxWindows

(.venv) $ git switch -c fix-win11-build

(.venv) $ git switch -c fix-win11-build

(.venv) C:\...>git switch -c fix-win11-build

Уникайте розширення обсягу робіт

Як уникнути розширення обсягу робіт

«Розширення обсягу робіт» відбувається тоді, коли перелік вирішених проблем або реалізованих функцій у рамках одного внеску значно перевищує те, що було заплановано на початку роботи. Ви починаєте з простої проблеми; потім виявляєте тісно пов’язану з нею проблему і вирішуєте включити й це виправлення; потім з’являється третя… і, перш ніж ви встигнете збагнути, у вас вже є запит на злиття, який закриває 5 проблем і додає 3 нові функції, включаючи десятки файлів.

Розширення обсягу робіт трапляється з кожним. Це поняття дуже добре знайоме досвідченим розробникам; ми всі не раз стикалися з цим і переживали всі пов’язані з цим проблеми.

Існують цілком практичні причини, щоб уникати розширення обсягу робіт. Чим більшим стає внесок, тим складніше з ним працювати. Стає важче виявляти крайні випадки або потенційні проблеми, а це означає, що загальна якість внеску може знизитися. Рецензування також стає складнішим, коли рецензенту доводиться мати справу з кількома, потенційно не пов’язаними між собою, контекстами. Більший внесок означає більше коментарів під час рецензування, і автору може стати складно стежити за кількома нитками обговорення. Навіть ваш досвід роботи з GitHub погіршиться — інтерфейс GitHub працюватиме повільніше у міру зростання розміру PR, а це означає, що навігація по файлах через інтерфейс GitHub та спроби залишати коментарі під час рецензування ставатимуть дедалі складнішими.

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

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

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

Впровадити нову функцію

Написання, виконання та тестування коду

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

Щоб розпочати роботу над кодом, переконайтеся, що у вас налагоджено середовище розробки і що ви працюєте над гілкою

У нас є посібник зі стилю написання коду, в якому викладені наші рекомендації щодо написання коду для BeeWare.

Розробка на основі тестування

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

Запустіть свій код

Після написання коду потрібно переконатися, що він працює. Вам доведеться вручну запустити код, щоб перевірити, чи він працює так, як ви очікуєте. Якщо ви ще цього не зробили, варто написати тестовий приклад для ваших змін; як зазначалося вище, цей тест повинен завершитися невдачею, якщо код закомментований або відсутній.

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

Виконання тестів та вимірювання покриття

BeeWare використовує tox для управління процесом тестування та pytest для власного набору тестів.

Команда tox за замовчуванням передбачає виконання:

• хуки перед комітом
• towncrier перевірка приміток до випуску

• перевірка документації на дотримання стилістики

• набір тестів для доступних версій Python

• звіти про покриття коду

По суті, саме це виконує CI, коли ви надсилаєте запит на злиття.

Щоб запустити повний набір тестів, виконайте наступну команду:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

Виконання повного набору тестів може зайняти деякий час. Ви можете значно пришвидшити цей процес, запустивши tox паралельно, за допомогою команди tox p (або tox run-parallel). Якщо ви запускаєте набір тестів паралельно, ви отримаєте менше інформації про хід виконання тестів під час їх роботи, але все одно отримаєте звіт про виявлені проблеми наприкінці тестування. Ви повинні отримати вихідні дані, що вказують на те, що тести були виконані. Ви можете побачити SKIPPED тестів, але ніколи не повинні отримувати жодних результатів тестів FAIL або ERROR. Ми запускаємо повний набір тестів перед злиттям кожного патча. Якщо під час цього процесу виявляються якісь проблеми, ми не зливаємо патч. Якщо ви все-таки виявили помилку або збій у тесті, це означає, що або у вашому тестовому середовищі є щось незвичайне, або ви знайшли крайній випадок, якого ми раніше не бачили — у будь-якому разі, повідомте нам про це!

Окрім успішного виконання тестів, це має забезпечити 100% покриття тестами.

Виконання варіантів тестів

Виконати тести для декількох версій Python

За замовчуванням багато команд tox намагатимуться запустити набір тестів кілька разів — по одному разу для кожної версії Python, що підтримується BeeWare. Однак для цього кожна з цих версій Python має бути встановлена на вашому комп’ютері та доступна для процесу [виявлення]tox Python, що виконується (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). Загалом, якщо версія Python доступна через PATH, то tox має змогу її знайти та використовувати.

Виконати лише набір тестів

Якщо ви швидко вдосконалюєте нову функцію, вам не потрібно запускати повний набір тестів; ви можете запустити лише модульні тести. Для цього виконайте наступну команду:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Виконати підмножину тестів

За замовчуванням команда tox запускає всі тести з набору модульних тестів. Під час розробки нового тесту може бути корисно запустити лише цей один тест. Для цього можна передати будь-який специфікатор pytest як аргумент до tox. Ці шляхи до тестів є відносними до каталогу briefcase. Наприклад, щоб запустити лише тести з одного файлу, виконайте:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

Ви все одно отримаєте звіт про покриття при виконанні частини набору тестів, але в результатах покриття будуть вказані лише ті рядки коду, які були виконані саме тими тестами, які ви запустили.

Запустити набір тестів для конкретної версії Python

За замовчуванням tox -e py виконуватиметься з використанням того інтерпретатора, який на вашому комп’ютері розпізнається як python. Якщо у вас встановлено кілька версій Python і ви хочете протестувати конкретну версію з-поміж встановлених, ви можете вказати конкретну версію Python для використання. Наприклад, щоб запустити набір тестів на Python 3.10, виконайте:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

Підмножину тестів можна запустити, додавши -- та специфікацію тесту до командного рядка.

Запустити набір тестів без перевірки покриття (швидко)

За замовчуванням tox запускає набір тестів pytest у однопотоковому режимі. Ви можете пришвидшити виконання набору тестів, запустивши його паралельно. У цьому режимі файли покриття не створюються через складнощі з фіксацією покриття в запущених процесах. Щоб запустити окрему версію Python у «швидкому» режимі, виконайте:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Підмножину тестів можна запустити, додавши -- та специфікацію тесту до командного рядка; конкретну версію Python можна використовувати, додавши версію до об’єкта тестування (наприклад, py310-fast для швидкого виконання на Python 3.10).

Покриття коду

BeeWare забезпечує 100% покриття гілок у своїй кодовій базі. Коли ви додаєте або змінюєте код у проєкті, вам необхідно додати тестовий код, щоб забезпечити покриття всіх внесених змін.

Однак BeeWare призначений для роботи на різних платформах, а також з різними версіями Python, тому повне покриття неможливо перевірити лише на одній платформі та в одній версії Python. Щоб врахувати це, у розділі tool.coverage.coverage_conditional_plugin.rules файлу pyproject.toml визначено кілька умовних правил покриття (наприклад, no-cover-if-is-windows можна використовувати для позначення блоку коду, який не виконуватиметься під час запуску набору тестів у Windows). Ці правила використовуються для виявлення фрагментів коду, які покриваються лише на певних платформах або у певних версіях Python.

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

Розуміння результатів охоплення

У кінці виводу результатів тесту на покриття має бути звіт із зібраними даними про покриття:

Назва    Звіти   Відділення «Місс» Частина «Бр»   Покриття   Відсутні
 ---------------------------------------------------
 ВСЬОГО    7540 0   1040 0  100,0 %

Це свідчить про те, що набір тестів перевірив усі можливі варіанти виконання коду. Це не є 100-відсотковою гарантією відсутності помилок, але означає, що ми перевіряємо кожен рядок коду в кодовій базі.

Якщо ви внесете зміни до коду, можливо, у покритті з’явиться прогалина. У такому випадку звіт про покриття покаже, які рядки не виконуються. Наприклад, припустимо, ми внесли зміну до some/interesting_file.py, додавши нову логіку. Звіт про покриття може виглядати приблизно так:

Ім'я Заяви   Міс Бранч БрПарт  Обкладинка   Відсутні
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1%   170, 302–307, 320–335
 -------------------------------------------------------------------------------
 ВСЬОГО 7540 1   1726 0  99,9%

Це свідчить про те, що рядок 170, рядки 302–307, а також перехід із рядка 320 до рядка 335 не виконуються набором тестів. Щоб відновити цей рівень покриття, вам потрібно додати нові тести (або змінити існуючий тест).

Звіт про сумісність з платформою-господарем та версією Python

Ви можете створити звіт про покриття для вашої платформи та версії Python. Наприклад, щоб запустити набір тестів і створити звіт про покриття для Python 3.10, виконайте наступну команду:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Звіт про охоплення для платформи-господаря

Якщо tox має доступ до всіх підтримуваних версій Python, то звіт про покриття для хост-платформи можна отримати, виконавши наступну команду:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Звіти про охоплення у форматі HTML

Звіт про покриття HTML можна створити, додавши -html до будь-якої назви середовища покриття tox, наприклад:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Справа не лише в написанні тестів!

Хоча ми дбаємо про те, щоб перевіряти весь наш код, завдання полягає не лише у підтримці такого рівня тестування. Частина завдання полягає в тому, щоб перевіряти код у процесі роботи. Можна написати вичерпний набір тестів для конкретного рятувального жилета… але цей конкретний рятувальний жилет все одно буде непридатним для тієї мети, для якої його призначено!

Під час розробки тестів вам слід також перевіряти, чи є основний модуль послідовним у своїй внутрішній структурі. Якщо ви помітите назви методів, які не є внутрішньо узгодженими (наприклад, щось називається on_select в одному модулі, а в іншому — on_selected), або випадки, коли дані обробляються непослідовно, позначте це та повідомте нам, створивши квиток. Або, якщо ви впевнені, що знаєте, що потрібно зробити, створіть pull-запит, який виправляє виявлену вами проблему.

Як тільки все запрацює, ви зможете надіслати запит на злиття зі своїми змінами.

Створити документацію

Будівельна документація

Перш ніж вносити будь-які зміни до документації BeeWare, варто переконатися, що ви можете зібрати існуючу документацію.

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

У вас обов'язково має бути встановлений інтерпретатор Python 3.13, який має бути доступний у шляху (тобто python3.13 має запускати інтерпретатор Python 3.13).

BeeWare використовує tox для створення документації. Наведені нижче команди tox необхідно виконувати з того самого каталогу, що й файл tox.ini, який знаходиться в кореневому каталозі проєкту.

Попередній перегляд документації в режимі реального часу

Для зручності швидкого редагування документації BeeWare має режим «попереднього перегляду в режимі реального часу».

Попередній перегляд у режимі реального часу буде сформовано з попередженнями!

Сервер у режимі реального часу доступний для ітеративного оновлення вашої документації. Під час оновлення ви можете допустити помилку в розмітці. Проблеми, позначені як WARNING, призведуть до збою стандартної збірки, однак робочий сервер налаштований так, що під час продовження збірки у консолі відображаються попередження. Це дозволяє вам вносити зміни без необхідності перезапуску попереднього перегляду.

WARNING відрізняється від ERROR. Якщо ви створите проблему, яка вважається ERROR, робочий сервер вийде з ладу і потребуватиме перезапуску. Він не запуститься знову, доки проблема ERROR не буде вирішена.

Щоб запустити сервер у режимі реального часу:

macOSLinuxWindows

(venv) $ tox -e docs-live

(venv) $ tox -e docs-live

(venv) C:\...>tox -e docs-live

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

Після запуску сервера у виведенні консолі ви побачите щось на зразок такого:

ІНФО    -  [11:18:51] Обслуговування на http://127.0.0.1:8000/

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

docs-live — це перший крок

Запуск docs-live для роботи з робочим сервером призначений для початкового циклу розробки. Перед надсиланням запиту на злиття (pull request) вам слід завжди запускати локальну збірку.

Локальна збірка

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

Створення локальної збірки

Щоб створити локальну збірку:

macOSLinuxWindows

(venv) $ tox -e docs

(venv) $ tox -e docs

(venv) C:\...>tox -e docs

Результати цієї збірки будуть розміщені в каталозі _build у кореневому каталозі проєкту.

Створення локальної перекладеної збірки

Документація BeeWare перекладена на кілька мов. Оновлення англійської версії документації можуть спричинити проблеми в версіях іншими мовами. Перед надсиланням запиту на злиття важливо переконатися, що всі версії працюють належним чином.

Щоб створити збірку всіх доступних перекладів:

macOSLinuxWindows

(дієслово) $ tox -e docs-all

(дієслово) $ tox -e docs-all

(venv) C:\...>tox -e docs-all

Результати компіляції кожної мовної версії будуть розміщені у відповідному каталозі _build/html/<languagecode>, де <languagecode> — це дво- або п’ятисимвольний код мови, пов’язаний із конкретною мовою (наприклад, fr для французької, it для італійської тощо).

Якщо ви виявили проблему з окремою збіркою, ви можете запустити цю збірку окремо, виконавши команду tox -e docs-<languagecode>. Наприклад, щоб зібрати лише французьку документацію, виконайте:

macOSLinuxWindows

(venv) $ tox -e docs-fr

(venv) $ tox -e docs-fr

(venv) C:\...>tox -e docs-fr

Результати одномовного компілювання будуть розміщені в каталозі _build.

Перевірка документації на дотримання стилістичних правил

Процес збірки виявлятиме проблеми з Markdown, але BeeWare виконує деякі додаткові перевірки стилю та форматування, відомі як «лінтинг». Щоб запустити перевірки лінтингу:

macOSLinuxWindows

(venv) $ tox -e docs-lint

(venv) $ tox -e docs-lint

(venv) C:\...>tox -e docs-lint

Це дозволить переконатися, що документація не містить:

• непрацюючі гіперпосилання
• слова з орфографічними помилками

Якщо правильне написання слова визнається помилковим, додайте це слово до списку в docs/spelling_wordlist. Таким чином слово буде додано до словника програми перевірки орфографії. Під час додавання до цього списку пам’ятайте:

• Ми віддаємо перевагу американській орфографії, допускаючи певні відхилення у вигляді специфічних для програмування розмовних слів (наприклад, «apps») та перетворення іменників на дієслова (наприклад, «scrollable»)
• У будь-якому згадуванні назви продукту слід дотримуватися рекомендованого способу написання з великої літери (наприклад, «macOS», «GTK», «pytest», «Pygame», «PyScript»).
• Якщо термін використовується «як код», його слід взяти в лапки як літерал (like this), а не додавати до словника.

Після успішного створення документації ви готові до написання документації.

Скласти документацію

Написання документації

Ось покрокова інструкція щодо написання вашого внеску у вигляді документації для BeeWare.

Перш ніж приступити до написання документації, переконайтеся, що ви можете скласти документацію і що ви працюєте на гілці.

Оновлення наявної документації

Якщо ви редагуєте існуючі документи, вам потрібно знайти файл у каталозі /docs/en. Структура файлів відповідає структурі сторінок, тому ви можете знайти файл за допомогою URL-адреси документації.

Додавання нової документації

Якщо ви додаєте новий документ, потрібно виконати ще кілька кроків.

Вам потрібно створити документ у відповідній папці каталогу docs/en. Для прикладу припустимо, що ви додаєте новий документ з іменем new_doc.md.

Далі вам потрібно буде оновити файл docs/en/SUMMARY.md, щоб додати до нього ваш новий файл. Файл SUMMARY.md побудований таким чином, щоб, по суті, віддзеркалювати структуру каталогів docs/en, але, що важливіше, він безпосередньо визначає структуру лівої бічної панелі. Якщо ви знайдете розділ, куди плануєте додати new_doc.md, вам не потрібно нічого змінювати у файлі SUMMARY.md, якщо там вказано шлях із символами-замінниками. Наприклад:

- ./шлях/до/каталогу/*

Якщо розділ, у який ви плануєте вставити new_doc.md, є списком окремих посилань у форматі Markdown, вам потрібно буде додати явне посилання на ваше посилання. Наприклад:

- [Мій новий документ](new_doc.md)

Складання документації

Тепер ви можете відкрити потрібний файл у редакторі та почати писати.

У нас є посібник зі стилю документації, в якому викладено наші рекомендації щодо написання документації для BeeWare.

Коли ви будете задоволені своєю новою документацією, ви зможете надіслати запит на злиття із запропонованими змінами.

Додати примітку про зміну

Додавання інформації про зміни до приміток до випуску

Багато інструментів BeeWare використовують towncrier для полегшення створення приміток до кожного релізу. Коли ви надсилаєте запит на злиття (pull request) до одного з відповідних інструментів, він повинен містити примітку про зміну — ця примітка стане записом у примітках до релізу, що описує внесену зміну.

Кожен pull-запит повинен містити принаймні один файл у каталозі changes/, який містить короткий опис змін, що впроваджуються цим pull-запитом. Примітка щодо зміни повинна бути у форматі Markdown, у файлі з іменем у форматі <id>.<fragment type>.md. Якщо запропонована вами зміна виправляє помилку або реалізує функцію, для якої вже існує номер проблеми, ідентифікатором буде номер цього квитка. Якщо зміна не має відповідної проблеми, як ідентифікатор можна використовувати номер PR. Ви не знатимете цього номера PR, доки не відправите запит на злиття, тому перший прохід CI не пройде перевірку towncrier; додайте примітку про зміну та відправте оновлення PR, після чого CI має пройти успішно.

Існує п’ять типів фрагментів:

• feature: Цей PR додає нову функцію або можливість, яка раніше була недоступна (наприклад, додавання підтримки нового формату пакування або нової функції в існуючому форматі пакування);
• bugfix: Цей PR виправляє помилку в існуючій реалізації;
• doc: Цей прес-реліз є суттєвим вдосконаленням документації;
• removal; Цей PR передбачає зміну в API BeeWare, що несумісна з попередніми версіями; або
• misc; Незначна або адміністративна зміна (наприклад, виправлення друкарської помилки, незначне уточнення формулювання або оновлення версії залежності), про яку не потрібно повідомляти в примітках до випуску.

Цей опис у примітці до зміни має бути загальним «маркетинговим» резюме зміни з точки зору користувача, а не глибоким технічним описом чи деталями реалізації. Вона відрізняється від повідомлення про коміт — повідомлення про коміт описує, що було зроблено, щоб майбутні розробники могли зрозуміти логіку зміни; примітка про зміну — це опис, призначений для користувачів, які можуть не мати знань про внутрішні механізми роботи системи.

Наприклад, якщо ви виправили помилку, пов’язану з іменами проектів, повідомлення про коміт може виглядати так:

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

Відповідна записка про зміну могла б виглядати приблизно так:

Назви проектів більше не можуть починатися з цифри.

Деякі PR можуть містити кілька нових функцій і виправлень помилок або кілька змін, несумісних із попередніми версіями. У такому випадку PR може мати кілька файлів з описом змін. Якщо вам потрібно пов’язати два типи фрагментів з одним і тим самим ідентифікатором, ви можете додати числовий суфікс. Наприклад, якщо PR 789 додав функцію, описану в квитку 123, виправив помилку, описану в квитку 234, а також вніс дві зміни, несумісні з попередніми версіями, у вас може бути 4 файли з примітками про зміни:

• 123.feature.md
• 234.bugfix.md
• 789.removal.1.md
• 789.removal.2.md

Більше інформації про towncrier та типи фрагментів див. у розділі Фрагменти новин. Ви також можете ознайомитися з існуючими прикладами фрагментів новин у каталозі changes репозиторію BeeWare. Якщо ця папка порожня, це, ймовірно, пов’язано з тим, що BeeWare нещодавно опублікував новий випуск; файли з примітками до змін видаляються та об’єднуються для оновлення приміток до випуску з кожним випуском. Ви можете переглянути цей файл, щоб ознайомитися з необхідним стилем коментарів; також можна переглянути нещодавно об’єднані PR, щоб дізнатися, як оформлювати свої нотатки про зміни.

Надіслати запит на злиття

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

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

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

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

Нижче наведено приклад того, що можна побачити на 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» і виберіть гілку, з якої ви хочете надіслати свій 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) міг бути переглянутий, можливо, знадобиться додати додатковий вміст, наприклад примітку про зміну.