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

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

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

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

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

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

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

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

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

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

Внедрить новую функцию

Fixing a bug or implementing a feature will require you to write some new code.

We have a code style guide that outlines our guidelines for writing code for BeeWare.

Test-driven development¶

A good way to ensure your code is going to do what you expect it to, is to first write a test case to test for it. This test case should fail initially, as the code it is testing for is not yet present. You can then write the code changes needed to make the test pass, and know that what you've written is solving the problem you are expecting it to.

Run your code¶

Once your code is written, you need to ensure it runs. You'll need to manually run your code to verify it is doing what you expect. If you haven't already, you'll want to write a test case for your changes; as mentioned above, this test should fail if your code is commented out or not present.

You'll add your test case to the test suite, so it can be run alongside the other tests. The next step is to run the test suite.

Running tests and coverage¶

BeeWare uses tox to manage the testing process and pytest for its own test suite.

The default tox command includes running:

pre-commit hooks
towncrier release note check
documentation linting
test suite for available Python versions
code coverage reporting

This is essentially what is run by CI when you submit a pull request.

To run the full test suite, run:

macOSLinuxWindows

(.venv) $ tox

(.venv) $ tox

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

The full test suite can take a while to run. You can speed it up considerably by running tox in parallel, by running tox p (or tox run-parallel). When you run the test suite in parallel, you'll get less feedback on the progress of the test suite as it runs, but you'll still get a summary of any problems found at the end of the test run. You should get some output indicating that tests have been run. You may see SKIPPED tests, but shouldn't ever get any FAIL or ERROR test results. We run our full test suite before merging every patch. If that process discovers any problems, we don't merge the patch. If you do find a test error or failure, either there's something odd in your test environment, or you've found an edge case that we haven't seen before - either way, let us know!

In addition to the tests passing, this should report 100% test coverage.

Running test variations¶

Run tests for multiple versions of Python¶

By default, many of the tox commands will attempt to run the test suite multiple times, once for each Python version supported by BeeWare. To do this, though, each of the Python versions must be installed on your machine and available to tox's Python discovery process. In general, if a version of Python is available via PATH, then tox should be able to find and use it.

Run only the test suite¶

If you're rapidly iterating on a new feature, you don't need to run the full test suite; you can run only the unit tests. To do this, run:

macOSLinuxWindows

(.venv) $ tox -e py

(.venv) $ tox -e py

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

Run a subset of tests¶

By default, tox will run all tests in the unit test suite. When you're developing your new test, it may be helpful to run just that one test. To do this, you can pass in any pytest specifier as an argument to tox. These test paths are relative to the briefcase directory. For example, to run only the tests in a single file, run:

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

You'll still get a coverage report when running a part of the test suite - but the coverage results will only report the lines of code that were executed by the specific tests you ran.

Run the test suite for a specific Python version¶

By default tox -e py will run using whatever interpreter resolves as python on your machine. If you have multiple Python versions installed, and want to test a specific Python version from the versions you have installed, you can specify a specific Python version to use. For example, to run the test suite on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -e py310

(.venv) $ tox -e py310

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

A subset of tests can be run by adding -- and a test specification to the command line.

Run the test suite without coverage (fast)¶

By default, tox will run the pytest suite in single threaded mode. You can speed up the execution of the test suite by running the test suite in parallel. This mode does not produce coverage files due to complexities in capturing coverage within spawned processes. To run a single python version in "fast" mode, run:

macOSLinuxWindows

(.venv) $ tox -e py-fast

(.venv) $ tox -e py-fast

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

A subset of tests can be run by adding -- and a test specification to the command line; a specific Python version can be used by adding the version to the test target (e.g., py310-fast to run fast on Python 3.10).

Code coverage¶

BeeWare maintains 100% branch coverage in its codebase. When you add or modify code in the project, you must add test code to ensure coverage of any changes you make.

However, BeeWare targets multiple platforms, as well as multiple versions of Python, so full coverage cannot be verified on a single platform and Python version. To accommodate this, several conditional coverage rules are defined in the tool.coverage.coverage_conditional_plugin.rules section of pyproject.toml (e.g., no-cover-if-is-windows can be used to flag a block of code that won't be executed when running the test suite on Windows). These rules are used to identify sections of code that are only covered on particular platforms or Python versions.

Of note, coverage reporting across Python versions can be a bit quirky. For instance, if coverage files are produced using one version of Python but coverage reporting is done on another, the report may include false positives for missed branches. Because of this, coverage reporting should always use the oldest version Python used to produce the coverage files.

Understanding coverage results¶

At the end of the coverage test output there should be a report of the coverage data that was gathered:

Name    Stmts   Miss Branch BrPart   Cover   Missing
----------------------------------------------------
ИТОГО 7540 0 1040 0 100,0%

This tells us that the test suite has executed every possible branching path in the code. This isn't a 100% guarantee that there are no bugs, but it does mean that we're exercising every line of code in the codebase.

If you make changes to the codebase, it's possible you'll introduce a gap in this coverage. When this happens, the coverage report will tell you which lines aren't being executed. For example, lets say we made a change to some/interesting_file.py, adding some new logic. The coverage report might look something like:

Имя Stmts Мисс Бранч BrPart Обложка отсутствует
--------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98,1% 170, 302-307, 320->335
--------------------------------------------------------------------------------
ИТОГО 7540 1 1726 0 99,9%

This tells us that line 170, lines 302-307, and a branch jumping from line 320 to line 335, are not being executed by the test suite. You'll need to add new tests (or modify an existing test) to restore this coverage.

Coverage report for host platform and Python version¶

You can generate a coverage report for your platform and version of Python. For example, to run the test suite and generate a coverage report on Python 3.10, run:

macOSLinuxWindows

(.venv) $ tox -m test310

(.venv) $ tox -m test310

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

Coverage report for host platform¶

If all supported versions of Python are available to tox, then coverage for the host platform can be reported by running:

macOSLinuxWindows

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

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

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

Coverage reporting in HTML¶

A HTML coverage report can be generated by appending -html to any of the coverage tox environment names, for instance:

macOSLinuxWindows

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

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

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

It's not just about writing tests!¶

Although we ensure that we test all of our code, the task isn't just about maintaining that level of testing. Part of the task is to audit the code as you go. You could write a comprehensive set of tests for a concrete life jacket… but a concrete life jacket would still be useless for the purpose it was intended!

As you develop tests, you should be checking that the core module is internally consistent as well. If you notice any method names that aren't internally consistent (e.g., something called on_select in one module, but called on_selected in another), or where the data isn't being handled consistently, flag it and bring it to our attention by raising a ticket. Or, if you're confident that you know what needs to be done, create a pull request that fixes the problem you've found.

///

/// details-abstract | Создать документацию

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



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

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

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

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

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

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

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

///

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



/// tab | macOS



```console
(venv) $ tox -e docs-live

LinuxWindows

(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, или вы не предоставите объяснение, почему это не так.