Внедрение новой функции

После завершения процесса предложения у вас должен быть готовый проект новой функции. Это значит, что пора приступать к написанию!

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

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

Внедрение новых функций

Настройте среду разработки

Для участия в BeeWare необходимо настроить среду разработки.

Предпосылки

Вам необходимо установить следующие предварительные компоненты.

macOSLinuxWindows

BeeWare требует Python 3.10+. Вам также понадобится метод для управления виртуальными средами (например, venv).

Вы можете проверить версию Python, которую вы установили, запустив:

Python 3.8.10 (по умолчанию, 20 июля 2020 г., 16:16:00)

Если у вас установлено более одной версии Python, вам может потребоваться заменить python3 конкретным номером версии (например, python3.13)

Мы рекомендуем избегать недавно выпущенных версий Python (т. е. версий с микроверсией «.0» или «.1», например 3.14.0). Это связано с тем, что инструменты, необходимые для поддержки Python в macOS, часто отстают и обычно недоступны для недавно выпущенных стабильных версий Python.

BeeWare требует Python 3.10+. Вам также понадобится метод для управления виртуальными средами (например, venv).

Вы можете проверить версию Python, которую вы установили, запустив:

Python 3.8.10 (по умолчанию, 20 июля 2020 г., 16:16:00)

Если у вас установлено более одной версии Python, вам может потребоваться заменить python3 конкретным номером версии (например, python3.13)

Мы рекомендуем избегать недавно выпущенных версий Python (т. е. версий с микроверсией «.0» или «.1», например 3.14.0). Это связано с тем, что инструменты, необходимые для поддержки Python в Linux, часто отстают и обычно недоступны для недавно выпущенных стабильных версий Python.

BeeWare требует Python 3.10+. Вам также понадобится метод для управления виртуальными средами (например, venv).

Вы можете проверить версию Python, которую вы установили, запустив:

C:\...>py -3 --version

Если у вас установлено несколько версий Python, возможно, вам потребуется заменить -3 конкретным номером версии (например, -python3.13)

Мы рекомендуем избегать недавно выпущенных версий Python (т. е. версий с микроверсией «.0» или «.1», например 3.14.0). Это связано с тем, что инструменты, необходимые для поддержки Python в Windows, часто отстают и обычно недоступны для недавно выпущенных стабильных версий Python.

Настройте свою среду разработки

Рекомендуемый способ настройки среды разработки для BeeWare — использовать виртуальную среду, а затем установить версию BeeWare для разработчиков и ее зависимости.

Склонируйте репозиторий BeeWare

Затем перейдите на страницу BeeWare на GitHub, и, если вы еще этого не сделали, создайте форк репозитория в своей учетной записи. Затем нажмите кнопку «<> Code» на вашем форке. Если на вашем компьютере установлено приложение GitHub Desktop, вы можете выбрать «Open with GitHub Desktop»; в противном случае скопируйте предоставленный URL-адрес HTTPS и используйте его для клонирования репозитория на свой компьютер с помощью командной строки:

macOSLinuxWindows

Сделайте форк репозитория BeeWare, а затем:

$ git clone https://github.com/<ваше имя пользователя>/beeware.git

(замените на свое имя пользователя GitHub)

Сделайте форк репозитория BeeWare, а затем:

$ git clone https://github.com/<ваше имя пользователя>/beeware.git

(замените на свое имя пользователя GitHub)

Сделайте форк репозитория BeeWare, а затем:

C:\...>git clone https://github.com/<ваше имя пользователя>/beeware.git

(замените на свое имя пользователя GitHub)

Установить исходный репозиторий

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

Вам также понадобятся теги из upstream, чтобы такие инструменты, как Toga и Briefcase, могли определять точные номера версий:

macOSLinuxWindows

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

$ git remote add upstream https://github.com/beeware/beeware.git
$ git fetch --tags upstream

C:\...>git remote add upstream https://github.com/beeware/beeware.git
C:\...>git fetch --tags upstream

Если вы хотите, чтобы ваша ветка также включала эти теги, вы можете их отправить:

$ git push --tags

Это может быть полезно, если вы позже создадите новый клон и захотите, чтобы теги были доступны из вашего форка.

Создать виртуальную среду

Чтобы настроить виртуальную среду и обновить pip, выполните:

macOSLinuxWindows

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

$ cd beeware
$ python3 -m venv .venv
$ source .venv/bin/activate
(.venv) $ python -m pip install -U pip

C:\...>cd beeware
C:\...>py -3 -m venv .venv
C:\...>.venv\Scripts\activate
(.venv) $ python -m pip install -U pip

Теперь перед вашим запросом должен стоять префикс (.venv).

Установить BeeWare

Теперь, когда у вас есть исходный код, вы можете выполнить редактируемую установку BeeWare в вашей среде разработки. Выполните следующую команду:

macOSLinuxWindows

(.venv) $ python -m pip install -U -e . --group dev

(.venv) $ python -m pip install -U -e . --group dev

(.venv) C:\...>python -m pip install -U -e . --group dev

Включить предварительную фиксацию

BeeWare использует инструмент под названием pre-commit, чтобы выявлять простые проблемы и стандартизировать форматирование кода. Для этого он устанавливает git-хук, который автоматически запускает серию линтеров кода перед финализацией любого git-коммита. Чтобы включить pre-commit, выполните:

macOSLinuxWindows

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) $ pre-commit install
pre-commit installed at .git/hooks/pre-commit

(.venv) C:\...>pre-commit install
pre-commit installed at .git/hooks/pre-commit

Теперь вы готовы приступить к взлому BeeWare!

Работа из филиала

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

Разработка на основе тестирования

Хороший способ убедиться, что ваш код будет работать так, как вы ожидаете, — сначала написать тестовый случай для его проверки. Изначально этот тестовый случай должен завершаться сбоем, поскольку тестируемый код ещё не реализован. Затем вы можете внести в код необходимые изменения, чтобы тест прошел успешно, и быть уверенным, что написанный вами код решает именно ту задачу, которую вы от него ожидали.

Запустите свой код

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

Вы добавите свой тестовый случай в набор тестов, чтобы его можно было запустить вместе с другими тестами. Следующим шагом будет запуск набора тестов.

Запуск тестов и покрытия

BeeWare использует tox для управления процессом тестирования и pytest для своего собственного набора тестов.

Команда tox по умолчанию включает в себя выполнение:

• хуки pre-commit
• towncrier Проверка примечаний к выпуску

• проверка документации на наличие синтаксических ошибок

• набор тестов для доступных версий Python

• отчеты по покрытию кода

По сути, именно это выполняет CI при отправке пул-реквеста.

Чтобы запустить полный набор тестов, выполните команду:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

(.venv) C:\...>tox

Выполнение полного набора тестов может занять некоторое время. Вы можете значительно ускорить этот процесс, запустив tox параллельно, то есть запустив tox p (или tox run-parallel). При параллельном запуске набора тестов вы будете получать меньше информации о ходе выполнения тестов, но по-прежнему получите сводку об обнаруженных проблемах по окончании тестирования. Вы должны увидеть вывод, подтверждающий, что тесты были запущены. Вы можете увидеть SKIPPED тестов, но ни в коем случае не должны получать результаты тестов FAIL или ERROR. Мы запускаем полный набор тестов перед слиянием каждого патча. Если в ходе этого процесса обнаруживаются какие-либо проблемы, мы не сливаем патч. Если вы обнаружили ошибку или сбой теста, либо в вашей тестовой среде есть что-то необычное, либо вы нашли крайний случай, с которым мы раньше не сталкивались — в любом случае, сообщите нам об этом!

Помимо успешного прохождения тестов, это должно обеспечить 100% покрытие тестами.

Выполнение вариантов тестов

Запустить тесты для нескольких версий Python

По умолчанию многие команды tox будут пытаться запустить набор тестов несколько раз — по одному разу для каждой версии Python, поддерживаемой BeeWare. Однако для этого каждая из версий Python должна быть установлена на вашем компьютере и доступна для процесса [обнаружения]tox Python в (https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery). Как правило, если версия Python доступна через PATH, то tox должна быть в состоянии найти и использовать её.

Запустить только набор тестов

Если вы быстро тестируете новую функцию, вам не нужно запускать полный набор тестов; можно запустить только модульные тесты. Для этого выполните команду:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

(.venv) C:\...>tox -e py

Запустить поднабор тестов

По умолчанию команда tox запускает все тесты из набора модульных тестов. При разработке нового теста может оказаться полезным запустить только этот один тест. Для этого в качестве аргумента команды pytest можно передать [любой спецификатор (https://docs.pytest.org/en/latest/how-to/usage.html#specifying-which-tests-to-run)]tox. Эти пути к тестам являются относительными по отношению к каталогу briefcase. Например, чтобы запустить только тесты из одного файла, выполните команду:

macOSLinuxWindows

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py

(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py

При запуске части набора тестов вы по-прежнему получите отчет о покрытии, однако в результатах будут указаны только те строки кода, которые были выполнены в рамках конкретных запущенных вами тестов.

Запустить набор тестов для конкретной версии Python

По умолчанию tox -e py будет запускаться с помощью того интерпретатора, который на вашем компьютере распознается как python. Если у вас установлено несколько версий Python и вы хотите протестировать одну из них, вы можете указать конкретную версию Python для использования. Например, чтобы запустить набор тестов на Python 3.10, выполните команду:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

(.venv) C:\...>tox -e py310

Подмножество тестов можно запустить, добавив символы -- и спецификацию теста в командную строку.

Запустить набор тестов без отслеживания покрытия (быстро)

По умолчанию команда tox запускает набор тестов pytest в однопоточном режиме. Вы можете ускорить выполнение набора тестов, запустив его в параллельном режиме. В этом режиме файлы покрытия не создаются из-за сложностей с отслеживанием покрытия в запущенных процессах. Чтобы запустить отдельную версию Python в «быстром» режиме, выполните команду:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

(.venv) C:\...>tox -e py-fast

Подмножество тестов можно запустить, добавив -- и спецификацию теста в командную строку; конкретную версию Python можно использовать, указав версию в целевом объекте теста (например, py310-fast для запуска fast на Python 3.10).

Покрытие кода

BeeWare обеспечивает 100% покрытие ветвей в своей кодовой базе. При добавлении или изменении кода в проекте необходимо добавлять тестовый код, чтобы обеспечить покрытие всех внесенных изменений.

Однако BeeWare предназначен для работы на нескольких платформах, а также с несколькими версиями Python, поэтому полное покрытие невозможно проверить на одной платформе и в одной версии Python. Чтобы учесть это, в разделе tool.coverage.coverage_conditional_plugin.rules файла pyproject.toml определено несколько условно-логических правил покрытия (например, no-cover-if-is-windows можно использовать для пометки блока кода, который не будет выполняться при запуске набора тестов в Windows). Эти правила используются для выявления участков кода, которые покрываются только на определенных платформах или в определенных версиях Python.

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

Понимание результатов покрытия

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

Название    Отчеты   Отделение Miss   Доля   Покрытие   Отсутствующие
 ---------------------------------------------------
 ИТОГО    7540 0   1040 0  100,0%

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

Если вы вносите изменения в исходный код, возможно, что в отчете о покрытии появятся пробелы. В таком случае отчет о покрытии покажет, какие строки не выполняются. Например, предположим, что мы внесли изменение в some/interesting_file.py, добавив новую логику. Отчет о покрытии может выглядеть примерно так:

Имя  Stmts  Miss  Branch  BrPart  Cover  Missing
 -------------------------------------------------------------------------------
 src/some/interesting_file.py 111 1     26 0  98,1%   170, 302-307, 320->335
 -------------------------------------------------------------------------------
 ИТОГО 7540 1   1726 0  99,9%

Это означает, что строка 170, строки 302–307, а также ветвление, переходящее со строки 320 на строку 335, не выполняются набором тестов. Чтобы восстановить покрытие, вам необходимо добавить новые тесты (или изменить существующий тест).

Отчет о поддержке платформы хоста и версии Python

Вы можете сгенерировать отчёт о покрытии для вашей платформы и версии Python. Например, чтобы запустить набор тестов и сгенерировать отчёт о покрытии для Python 3.10, выполните команду:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

(.venv) C:\...>tox -m test310

Отчет об охвате для хост-платформы

Если для tox доступны все поддерживаемые версии Python, то для получения отчета о покрытии для хост-платформы можно выполнить следующую команду:

macOSLinuxWindows

(.venv) $ tox p -m test-platform

(.venv) $ tox p -m test-platform

(.venv) C:\...>tox p -m test-platform

Отчеты об охвате в формате HTML

Отчет об охвате HTML можно сгенерировать, добавив -html к любому из имен сред охвата tox, например:

macOSLinuxWindows

(.venv) $ tox -e coverage-platform-html

(.venv) $ tox -e coverage-platform-html

(.venv) C:\...>tox -e coverage-platform-html

Дело не только в написании тестов!

Хотя мы и следим за тем, чтобы тестировать весь наш код, задача заключается не только в поддержании этого уровня тестирования. Часть задачи состоит в том, чтобы проводить аудит кода по ходу работы. Можно написать исчерпывающий набор тестов для конкретного спасательного жилета… но такой спасательный жилет всё равно будет бесполезен для тех целей, для которых он был предназначен!

При разработке тестов вам следует также проверять, насколько внутренне согласован основной модуль. Если вы заметили имена методов, которые не являются внутренне согласованными (например, что-то называется on_select в одном модуле, но on_selected в другом), или если данные обрабатываются несогласованно, отметьте это и сообщите нам, создав заявку. Или, если вы уверены, что знаете, что нужно сделать, создайте пул-реквест, исправляющий обнаруженную вами проблему.

Создать документацию

Прежде чем вносить какие-либо изменения в документацию BeeWare, рекомендуется убедиться, что вы можете скомпилировать существующую документацию.

Вы должны иметь установленный интерпретатор Python 3.13 и доступный в вашем пути (т. е. python3.13 должен запускать интерпретатор Python 3.13).

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

Предварительный просмотр документации в режиме реального времени

Для ускорения редактирования документации BeeWare имеет режим «предварительного просмотра».

Предварительный просмотр будет создаваться с предупреждениями!

Live Serve доступен для итерации обновлений вашей документации. Во время обновления вы можете столкнуться с проблемой разметки. Проблемы, обозначенные как WARNING, приведут к сбою стандартной сборки, однако Live Serve настроен так, что он отображает предупреждения в консольном выводе, продолжая сборку. Это позволяет вам выполнять итерацию без необходимости перезапуска Live Preview.

WARNING отличается от ERROR. Если вы введете проблему, которая считается ERROR, работа в режиме реального времени будет прервана, и потребуется перезапуск. Работа не возобновится до тех пор, пока проблема WARNING не будет решена.

Чтобы запустить рабочий сервер:

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

Локальная сборка

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

Создание локальной сборки

Чтобы сгенерировать локальную сборку:

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 для помощи в создании примечаний к каждому выпуску. Когда вы отправляете запрос на извлечение в один из соответствующих инструментов, он должен включать примечание об изменении — это примечание станет записью в примечаниях к выпуску, описывающей внесенное изменение.

Каждый пул-реквест должен содержать как минимум один файл в каталоге changes/, в котором дается краткое описание изменений, внесенных пул-реквестом. Заметка об изменениях должна быть в формате Markdown, в файле с именем формата <id>.<fragment type>.md. Если предлагаемое вами изменение исправляет ошибку или реализует функцию, для которой уже существует номер проблемы, то идентификатором будет номер этого тикета. Если изменение не имеет соответствующей проблемы, в качестве идентификатора можно использовать номер PR. Вы не узнаете этот номер PR, пока не отправите запрос на извлечение, поэтому первая проверка CI не пройдет проверку towncrier; добавьте примечание об изменении и отправьте обновление PR, после чего CI должна пройти.

Существует пять типов фрагментов:

• feature: PR добавляет новое поведение или возможность, которые ранее были недоступны (например, добавление поддержки нового формата упаковки или новой функции в существующем формате упаковки);
• bugfix: PR исправляет ошибку в существующей реализации;
• doc: PR значительно улучшает документацию;
• removal; данный PR вносит изменение в API BeeWare, несовместимое с предыдущими версиями; или
• misc; Незначительное или административное изменение (например, исправление опечатки, незначительное уточнение формулировки или обновление версии зависимости), которое не требует объявления в примечаниях к выпуску.

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

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

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

Соответствующее примечание об изменении будет выглядеть примерно так:

Названия проектов больше не могут начинаться с цифры.

Некоторые PR могут вводить несколько функций и исправлять несколько ошибок, либо вводить несколько изменений, несовместимых с предыдущими версиями. В этом случае PR может иметь несколько файлов с примечаниями об изменениях. Если вам нужно связать два типа фрагментов с одним и тем же ID, вы можете добавить числовой суффикс. Например, если 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 и создайте запрос на извлечение

При первом отправлении в GitHub вам будет предоставлен URL-адрес, по которому вы попадете прямо на страницу GitHub для создания нового запроса на извлечение. Перейдите по URL-адресу и создайте запрос на извлечение.

Ниже приведен пример того, что можно ожидать на 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» (Новый запрос на извлечение) и выберите, из какого репозитория вы хотите отправить запрос на извлечение.
• Если вы недавно выполняли push, перейдите в репозиторий upstream, найдите баннер над списком файлов, который указывает, что в репозитории «были недавние push», и нажмите кнопку «Сравнить и запросить pull».
• Используйте команду GitHub CLI gh pr create и заполните поля в соответствии с подсказками.
• Используйте команду GitHub CLI gh pr create --web, чтобы открыть веб-браузер на странице создания PR.

Любой из этих вариантов позволит вам создать новый пулл-реквест.

CLI GitHub: gh

GitHub предоставляет GitHub CLI, который дает вам доступ ко многим функциям GitHub из вашего терминала с помощью команды gh. В документации GitHub CLI описаны все функции.

Содержание запроса на извлечение

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

Описание PR должно четко отражать изменения в PR. Человек, не знакомый с контекстом, должен иметь возможность прочитать ваше описание и получить относительно полное представление о том, почему вносится данное изменение. Избегайте шуток, идиом, разговорных выражений и ненужного форматирования, такого как использование заглавных букв или чрезмерное использование знаков препинания; это должно быть прямое объяснение того, что происходит в вашем PR, и избегание этих вещей делает описание более доступным для других.

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

Если ваш пул-реквест решит проблему № 1234, вам следует включить текст `Fixes

1234` в описание пул-реквеста. Это приведет к автоматическому закрытию проблемы

при слиянии пул-реквеста. Вы можете ссылаться на другие обсуждения, проблемы или пул-реквесты, используя тот же синтаксис #1234. Вы можете ссылаться на проблему в другом репозитории, добавив перед номером префикс - например, python/cpython#1234 будет ссылаться на проблему 1234 в репозитории CPython.

Непрерывная интеграция

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

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

Когда CI завершается с ошибкой, ссылки на ошибки отображаются внизу страницы PR под заголовком «Некоторые проверки завершились с ошибкой». Вы увидите список неудачных проверок, который будет отображаться в верхней части списка всех проверок, если есть также успешные проверки. Если вы нажмете на ссылку с ошибкой, вы перейдете к журналу. Журнал часто содержит всю информацию, необходимую для выяснения причины сбоя. Прочитайте журнал и попытайтесь выяснить, почему происходит сбой, а затем сделайте все необходимое для его устранения.

Иногда проверка CI завершается сбоем по причинам, не связанным с вашими изменениями. Это может быть связано с проблемой на компьютере, на котором выполняется проверка CI, или с нестабильностью проверки CI. Если вы заметили сбой и уверены, что он не связан с вашими изменениями, добавьте соответствующий комментарий к вашему PR, и мы рассмотрим эту проблему.

Чтобы запустить новый цикл CI, вам необходимо отправить новые изменения в свою ветвь.

Если вы оказались в ситуации, когда вам нужна помощь в прохождении CI, оставьте комментарий в PR, сообщив нам об этом, и мы сделаем все возможное, чтобы помочь.

Проверки pre-commit и towncrier

Если проверка pre-commit или towncrier завершится с ошибкой, это заблокирует выполнение большинства остальных проверок CI. Вам необходимо будет устранить соответствующие проблемы, прежде чем будет запущен полный набор проверок.

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

Процесс подачи вашего PR не завершен, пока он не пройдет CI, или вы не предоставите объяснение, почему это не так.