Добавление документации

У вас может быть лучшее программное обеспечение в мире, но если никто не знает, как им пользоваться, какой в этом смысл? Документацию всегда можно улучшить, и нам нужна ваша помощь!

Формы документации

Документация BeeWare написана с использованием MkDocs и Markdown. Мы стремимся следовать структуре Diataxis при составлении документации.

Структура Diataxis описывает четыре «формы» документации:

• Учебное пособие — это руководство по обучению, ориентированное на конкретный конечный результат проекта.
• Практическое руководство — инструкции, которые помогают читателю достичь определенной цели или результата.
• Тематическое руководство — обсуждение одной идеи, объясненной таким образом, чтобы были понятны лежащие в ее основе концепции.
• Справочная информация — технические описания конкретных API или других интерфейсов.

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

В качестве примера рассмотрим задачу написания документации о выпечке печенья.

Учебное пособие

Учебник — это введение, в частности, ориентированное на начинающих, цель которого должна заключаться в том, чтобы привести читателя от нуля до готового продукта. Для этого требуются очень конкретные инструкции и подробные объяснения, которые помещают шаги учебника в контекст. Вы не должны делать никаких предположений об опыте читателя в использовании объясняемого инструмента, хотя разумно предположить, что он обладает некоторыми базовыми знаниями Python.

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

Учебник по выпечке печенья — это больше, чем просто рецепт. Инструкции в учебнике должны быть доступны для тех, кто никогда раньше не пек (например, для детей), и должны учитывать вещи, которые опытный пекарь считает само собой разумеющимися, такие как взбивание сахара и масла, процесс предварительного нагрева духовки или время, в течение которого печенье должно остывать перед употреблением. Цель учебника — не приготовить печенье, а донести основы выпечки. Полученное печенье — это вкусное лакомство, которое и побуждает человека пройти учебник.

Руководство по эксплуатации

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

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

Тематический справочник

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

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

Ссылка

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

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

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

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

Документация для авторов

Предложение новой документации

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Предпосылки

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

macOSLinuxWindows

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

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

$ python3 --version

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

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

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

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

$ python3 --version

Если у вас установлено более одной версии 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/<your username>/beeware.git

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

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

$ git clone https://github.com/<your username>/beeware.git

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

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

C:\...>git clone https://github.com/<your username>/beeware.git

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

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

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

Вы должны иметь установленный интерпретатор 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

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

После запуска сервера в консоли появится примерно следующее сообщение:

INFO    -  [11:18:51] Serving on 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

(venv) $ tox -e docs-all

(venv) $ 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, если вы видите перечень путей с подстановочными знаками. Например:

- ./path/to/directory/*

Если раздел, в который вы собираетесь включить new_doc.md, представляет собой список отдельных ссылок Markdown, вам необходимо добавить явную ссылку на свою. Например:

- [My new document](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; The PR represents a backwards incompatible change in the BeeWare API; or
• 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, или вы не предоставите объяснение, почему это не так.