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

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

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

Подумайте про те, що ви завжди мріяли створити, і спробуйте це зробити. Якщо виявиться, що вам вдалося реалізувати свій проект, вітаємо! Тепер у вас є те, про що ви завжди мріяли.

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

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

Використання інструментів для внесення вкладу

Повідомити про нову проблему

Подання нової проблеми

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

Пошук існуючих проблем

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

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

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

Почніть з обговорення

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

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

Як скласти якісний звіт про помилку

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

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

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

  • Версія вашої операційної системи — аж до мікроверсії (наприклад, macOS 15.7.2).
  • Ваша версія Python, включаючи мікроверсію (наприклад, 3.14.1).
  • Як ви встановили Python? Ви завантажили його з сайту python.org? Ви використовували Homebrew? uv? pyenv? conda? Щось інше?
  • Яку саме версію інструментів BeeWare ви використовуєте (наприклад, Toga 0.5.3)? Якщо ви використовуєте версію для розробників, який хеш Git ви використовуєте? Недостатньо просто сказати «поточна основна гілка», оскільки вона може змінюватися щодня.
  • Конкретні версії інших пакетів, які необхідно встановити, щоб відтворити цю проблему. Ви можете навести результати виконання команди python -m pip freeze, щоб надати цю інформацію.
  • Якщо файл журналу було створено, то весь файл журналу.
  • Якщо було згенеровано трасування стека, надайте повне трасування стека. Не обмежуйтеся лише кінцевим повідомленням про помилку — важливий повний контекст трасування стека. Також бажано надавати цю інформацію у текстовому форматі, а не у вигляді скріншоту.
  • Чи є ще якісь особливості налаштувань вашого комп’ютера або мережі, які можуть впливати на цю проблему? Чи є ваш комп’ютер застарілим або повільним? Чи це робочий комп’ютер, на якому можуть бути встановлені брандмауери, антивірусні програми або інші обмеження? Чи ваша мережа працює особливо повільно? Чи використовуєте ви операційну систему з нестандартними налаштуваннями за замовчуванням (наприклад, дуже великим шрифтом або увімкненими допоміжними технологіями)?

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

Мінімальний приклад

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

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

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

Крім того, у будь-яких інструкціях щодо відтворення проблеми слід бути чіткими. Фраза «Закрийте приклад програми» може означати натискання кнопки закриття у вікні, вибір пункту «Вийти» з меню або введення комбінації клавіш Control-C у терміналі. Ваше повідомлення не повинно залишати місця для двозначності щодо того, що саме потрібно зробити, щоб відтворити проблему.

Подання звіту

Перейдіть до списку проблем проекту, натисніть кнопку «Нова проблема» та виберіть «Звіт про помилку», щоб розпочати процес.

Ви повинні заповнити усі розділи шаблону повідомлення. Ми надаємо цей шаблон як підказку, щоб допомогти вам вказати необхідну інформацію. Пам’ятайте: ви завжди можете (і повинні!) надавати більше інформації, ніж вимагає шаблон, але як мінімум нам потрібна вся інформація, що міститься в шаблоні.

Додаючи код, якщо його можна відтворити за допомогою існуючого прикладу, наприклад, з підручника BeeWare, можна вказати посилання. В іншому випадку код слід навести безпосередньо у звіті. Він має бути відформатований у стилі Markdown; блок коду потрібно оточити трьома зворотними лапками (```) з обох боків.

Якщо вам потрібно вставити великий фрагмент тексту, ви можете зробити його згорнутим, скориставшись таким синтаксисом:

<details>
<summary>Заголовка згорнутого вмісту</summary>
Довгий блок тексту.
</details>

Після того як ви вкажете якомога більше інформації, натисніть «Створити», щоб надіслати звіт.

Створення запиту за допомогою GitHub CLI

Пряме використання GitHub CLI (gh) дозволяє обійти створені нами шаблони. Ці шаблони призначені для того, щоб гарантувати, що ми отримаємо всю необхідну інформацію для вирішення проблеми.

Якщо ви збираєтеся використовувати gh для створення нової проблеми, будь ласка, скористайтеся наступним:

gh issue create --web

Використання --web відкриває у браузері сторінку шаблону запиту та дозволяє створити запит за допомогою відповідного шаблону.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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