Перейти к содержанию

Использование инструментов

Одной из самых ценных форм обратной связи для нас являются отзывы людей, которые пробуют использовать инструменты 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>Collapsed content title</summary>
Long block of text.
</details>

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

Предложить новую функцию

Итак, у вас есть идея по улучшению BeeWare — как вы можете подать эту идею на рассмотрение?

Проведите исследование

Первый шаг — это поиск в системе отслеживания проблем BeeWare существующих проблем с функциональностью (проблемы с тегом «enhancement»), проблем с документацией (проблемы с тегом «documentation») или теמות для обсуждения, чтобы проверить, не было ли эта идея предложена ранее. Если да, и у вас есть новый контекст или идеи, добавьте их в существующую ветку. Если вам нужна помощь в поиске, вы можете обратиться в канал #dev на BeeWare Discord. Мы можем указать вам существующие ветки, предоставить контекст, о котором вы, возможно, не знаете, или связать вашу идею с другой идеей, которая на первый взгляд может показаться не связанной.

Обсудить идею

Если вы не нашли никаких существующих ссылок на вашу идею, создайте тему для обсуждения. Опишите в общих чертах цель и варианты использования вашей идеи. Включите все свои соображения о том, как будет выглядеть эта функция в случае ее реализации, например, общую форму API, визуальный вид возможности или документ, который будет добавлен. Если это применимо, вы также должны включить любые исследования, которые вы провели о том, как ваша идея будет реализована на разных платформах.

Как только тема обсуждения будет открыта, команда BeeWare и остальные члены сообщества ответят на нее. Основная команда постарается дать хотя бы первое впечатление о вашей идее в течение двух рабочих дней. Если идея особенно сложная, более подробный анализ может занять до недели. Такие события, как праздники и конференции, могут немного удлинить эти сроки.

Это ваша возможность принять участие в обсуждении вашей идеи. Мы можем попросить вас предоставить более подробную информацию или контекст. Другие члены сообщества также могут принять участие в обсуждении, высказывая свои точки зрения, предложения или встречные предложения. Результаты этого обсуждения определят дальнейшие шаги.

Важно понимать, что не все идеи будут приняты. Этот процесс начинается с предложения, чтобы вы не вложили все свои усилия, а потом не обнаружили, что ваши изменения не будут приняты по какой-то причине.

Это не значит, что идея была плохой! Возможно, есть технические причины, по которым ее нельзя реализовать. Например, мы можем отклонить идею, если:

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

Если мы решим, что ваша идея не подходит, это не обязательно означает, что вы должны от нее отказаться. Хотя мы можем отклонить конкретную идею, мы можем быть гораздо более склонны добавить интерфейс плагина или другой пункт расширения, который позволит вам поддерживать ту же функцию в качестве внешней библиотеки. Таким образом, вы сможете иметь эту функцию, но без конкретных проблем с обслуживанием или ограничений, которые могут стать препятствием для самого проекта.

Преобразовать в официальный запрос на добавление функции

Как только в ходе обсуждения будет достигнут консенсус по поводу формы функции, вы можете создать новую заявку на функцию в системе отслеживания заявок BeeWare, в которой будет кратко изложено содержание обсуждения и приведена ссылка на него для контекста.

Вам не нужно самостоятельно реализовывать предложенную вами функцию; вы можете открыть заявку с подробным описанием вашего предложения. Однако простое размещение заявки не означает, что она будет реализована. Вам нужно будет подождать, пока ее потенциально подхватит кто-то другой, заинтересованный в той же функции, будь то другой член сообщества или основная команда; однако нет гарантии, что это произойдет. Если вы хотите гарантированную реализацию, вам нужно будет реализовать ее самостоятельно или заплатить кому-то другому, чтобы он реализовал ее для вас.