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

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

Форми документації

Документація BeeWare написана з використанням MkDocs та Markdown. Ми прагнемо дотримуватися фреймворку Diataxis для структурування документації.

Фреймворк Diataxis описує чотири «форми» документації:

• Посібник — керований процес навчання, що має конкретну кінцеву мету у вигляді реалізації проекту.
• Практичний посібник — інструкції, що допомагають читачеві досягти певної мети або результату.
• Тематичний посібник — розгляд однієї ідеї, викладеної таким чином, щоб основні поняття були зрозумілими.
• Довідкова інформація — Технічні описи конкретних API або інших інтерфейсів.

Перш ніж розпочинати роботу над будь-яким матеріалом для документації, важливо визначити, який формат підійде найкраще. Багато пропозицій щодо документації спочатку формулюються як запит на «посібник з X», але в більшості випадків насправді потрібні практичні інструкції, тематичний довідник або вдосконалена довідкова інформація.

Для прикладу розглянемо завдання з написання інструкції щодо випікання печива.

Посібник

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

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

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

Посібник з використання

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

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

Посібник з тем

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

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

Посилання

Довідкова документація має інформаційний характер і описує особливості роботи бібліотеки інструментів. Досить часто її можна створити на основі самого коду, але якісна документація до API може потребувати додаткових пояснень та контексту. Хоча іноді вона може містити приклади використання, слід уникати надто докладних пояснень.

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

Стиль оформлення документації

Документація BeeWare відповідає рекомендаціям, викладеним у посібнику зі стилю документації. Цей посібник містить основні правила стилю та форматування, а також опис процесу перевірки орфографії. Крім того, у ньому розглядаються різні деталі синтаксису Markdown, такі як синтаксис посилань, поради щодо роботи з блоками коду та обробка зображень.

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

Пропозиція щодо нової документації

Пропозиція щодо нової функції

Отже, у вас є пропозиція щодо вдосконалення BeeWare — як подати цю пропозицію на розгляд?

Проведіть дослідження

Першим кроком є пошук у системі відстеження проблем BeeWare існуючих запитів щодо нових функцій (запитів з тегом «enhancement»), проблем з документацією (записів із тегом «documentation»), або тем для обговорення, щоб перевірити, чи ця ідея вже пропонувалася раніше. Якщо так, і у вас є нові деталі чи ідеї, додайте їх до існуючої теми. Якщо вам потрібна допомога з пошуком, ви можете звернутися у каналі #dev на BeeWare Discord. Ми можемо вказати вам на існуючі теми, надати контекст, про який ви, можливо, не знаєте, або пов’язати вашу ідею з іншою, яка на перший погляд може здаватися не пов’язаною.

Обговоріть цю ідею

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

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

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

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

Це не означає, що це була погана ідея! Можливо, існують технічні причини, через які її неможливо реалізувати. Наприклад, ми можемо відхилити ідею, якщо:

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

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

Перетворити на офіційну пропозицію щодо функції

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

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

Якщо вас це зацікавило, ви можете розпочати реалізацію нової функції.

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

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

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

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

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

У вас обов'язково має бути встановлений інтерпретатор 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) міг бути переглянутий, можливо, знадобиться додати додатковий вміст, наприклад примітку про зміну.