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

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

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