Устранение проблемы¶

BeeWare отслеживает список известных проблем. Любая из этих проблем может стать предметом для работы.

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

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

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

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

Вклад в исправление проблемы¶

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

Для участия в 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

Воспроизвести проблему

Невозможно исправить проблему, если она изначально не существует. Поэтому воспроизведение проблемы является необходимым условием для ее устранения. В программном обеспечении проблемы обычно называют «ошибками» (https://en.wikipedia.org/wiki/Software_bug), а сообщения о них — «сообщениями об ошибках».

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

Ошибки в коде¶

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

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

Ошибки в документации¶

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

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

Обновите проблему¶

Последним шагом в процессе сортировки является документирование ваших выводов путем оставления комментария к проблеме.

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

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

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

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

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

Если для устранения проблемы требуется изменение кода:

Написание, запуск и тестирование кода

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