Отправка новой проблемы¶

Написание хорошего отчета о проблеме или ошибке может иметь решающее значение для устранения неполадки. Вот как отправить хороший отчет об ошибке в 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>Collapsed content title</summary>
Long block of text.
</details>

После того, как вы предоставили как можно больше информации, нажмите «Создать», чтобы отправить отчет.