diff --git a/docs/ru/docs/contributing.md b/docs/ru/docs/contributing.md new file mode 100644 index 0000000000..a4c9301849 --- /dev/null +++ b/docs/ru/docs/contributing.md @@ -0,0 +1,260 @@ +# Разработка - Вклад + +Для начала вам, возможно, захочется ознакомиться с основными способами [помочь проекту FastAPI и получить помощь](help-fastapi.md). + +## Разработка + +Если вы уже клонировали [репозиторий fastapi](https://github.com/fastapi/fastapi) и вы хотите глубоко погрузиться в код, вот несколько рекомендаций по настройке вашего окружения. + +### Установка зависимостей + +Создайте виртуальное окружение и установите необходимые пакеты с помощью [uv](https://github.com/astral-sh/uv): + +
+ +```console +$ uv sync --extra all + +---> 100% +``` + +
+ +Это установит все зависимости и вашу локальную версию FastAPI в локальное окружение. + +### Использование вашей локальной версии FastAPI + +Если вы создадите Python-файл, который импортирует и использует FastAPI, и запустите его с помощью Python из вашего локального окружения, он будет использовать клонированный вами локальный исходный код FastAPI. + +И если вы обновите этот локальной исходный код FastAPI, то при повторном запуске того же Python-файла будет использоваться свежая версия FastAPI, которую вы только что отредактировали. + +Таким образом, вам не нужно "устанавливать" вашу локальную версию, чтобы иметь возможность тестировать каждое изменение. + +/// note | Технические детали + +Это происходит только в том случае, если вы устанавливаете зависимость с помощью `uv sync --extra all`, а не запускаете `pip install fastapi` напрямую. + +Это связанно с тем, что `uv sync --extra all` по умолчанию устанавливает локальную версию FastAPI в "редактируемом (editable)" режиме. + +/// + +### Форматирование кода + +Существует скрипт, который вы можете запустить для форматирования и очистки всего вашего кода: + +
+ +```console +$ bash scripts/format.sh +``` + +
+ +Он также автоматически отсортирует все ваши импорты. + +## Тестирование + +Существует скрипт, который вы можете запустить локально для тестирования всего кода и создания отчетов о покрытии в формате HTML: + +
+ +```console +$ bash scripts/test-cov-html.sh +``` + +
+ +Эта команда создает директорию `./htmlcov/`. Если вы откроете файл `./htmlcov/index.html` в вашем браузере, вы сможете в интерактивном режиме изучить участки кода, которые покрыты тестами, если какие-то участки пропущены. + +## Документация + +Сначала убедитесь, что вы настроили свое окружение, как описано выше - это установит все необходимые зависимости. + +### Документация в реальном времени + +Во время локальной разработки существует скрипт, которые собирает сайт и отслеживает любые изменения с автоматической перезагрузкой. + +
+ +```console +$ python ./scripts/docs.py live + +[INFO] Serving on http://127.0.0.1:8008 +[INFO] Start watching changes +[INFO] Start detecting changes +``` + +
+ +Он запустит документацию по адресу `http://127.0.0.1:8008`. + +Таким образом, вы можете редактировать файлы документации/исходного кода и видеть изменения в реальном времени. + +/// tip | Совет + +Как вариант, вы можете вручную выполнить те же шаги, что и скрипт. + +Перейдите в директорию с языком, для основной документации на английском это `docs/en/`: + +```console +$ cd docs/en/ +``` +Затем запустите `mkdocs` в этой директории: + +```console +$ mkdocs serve --dev-addr 127.0.0.1:8008 +``` + +/// + +#### Typer CLI (опционально) + +Инструкции здесь показывают, как использовать скрипт `./scripts/docs.py` напрямую с программой `python`. + +Но вы также можете использовать [Typer CLI](https://typer.tiangolo.com/typer-cli/). После установки этой программы в вашем терминале появится автозавершение команд. + +Если вы установите Typer CLI, вы можете установить автодополнение с помощью: + +
+ +```console +$ typer --install-completion + +zsh completion installed in /home/user/.bashrc. +Completion will take effect once you restart the terminal. +``` + +
+ +### Структура документации + +Документация использует [MkDocs](https://www.mkdocs.org/). + +А также есть дополнительные инструменты/скрипты для работы с переводами в `./scripts/docs.py`. + +/// tip | Совет + +Вам не нужно изучать код в `./scripts/docs.py`, вы просто используете его из командной строки. + +/// + +Вся документация находится в формате Markdown в директории `./docs/en/`. + +Многие из руководств содержат блоки кода. + +В большинстве случаев эти блоки кода представляют собой полноценные приложения, которые можно запускать как есть. + +На самом деле эти блоки кода не написаны внутри Markdown, они представляют собой Python-файлы в директории `./docs_src/`. + +И эти Python-файлы включаются/внедряются в документацию при генерации сайта. + +### Документация для тестов + +Большинство тестов на самом деле выполняются на примерах исходных файлов из документации. + +Это помогает убедиться в том, что: + +* Документация актуальна. +* Примеры из документации можно запускать как есть. +* Большинство функций покрыто документацией, что подтверждается покрытием тестами. + +#### Приложения и документация одновременно + +Если вы запускаете примеры, например: + +
+ +```console +$ fastapi dev tutorial001.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +Поскольку Uvicorn по умолчанию использует порт 8000, документация на порту 8008 не будет конфликтовать. + +### Переводы + +Помощь с переводом ОЧЕНЬ ценится! И она невозможно без помощи сообщества. 🌎 🚀 + +Pull Request`ы с переводами создаются с помощью LLM, управляемых промптами, разработанными командой FastAPI совместно с сообществом носителей языка для каждого поддерживаемого языка. + +#### Промпт LLM для каждого языка + +У каждого языка есть своя директория: [https://github.com/fastapi/fastapi/tree/master/docs](https://github.com/fastapi/fastapi/tree/master/docs). В ней вы можете найти файл `llm-prompt.md` с промптом, специфичным для этого языка. + +Например, для испанского языка промпт находится здесь: [`docs/es/llm-prompt.md`](https://github.com/fastapi/fastapi/blob/master/docs/es/llm-prompt.md). + +Если вы заметите ошибки в вашем языке, вы можете предложить изменения в этом файле для вашего языка и запросить повторную генерацию конкретных страниц после внесения изменений. + +#### Проверка PR с переводами + +Вы также можете просмотреть существующие на данный момент [pull request](https://github.com/fastapi/fastapi/pulls) для вашего языка. Вы можете отфильтровать pull request по метке, соответствующей вашему языку. Например, для испанского языка метка — [`lang-es`](https://github.com/fastapi/fastapi/pulls?q=is%3Aopen+sort%3Aupdated-desc+label%3Alang-es+label%3Aawaiting-review). + +При проверке pull request лучше не предлагать изменения в том же самом pull request, поскольку он создан LLM, и невозможно гарантировать, что небольшие индивидуальные правки будут воспроизведены в других похожих разделах или сохранятся при повторном переводе того же самого содержимого. + +Вместо добавления предложений в PR с переводом, внесите предложения в файл промпта LLM для этого языка в новом PR. Например, для испанского языка файл промпта LLM находится здесь: [`docs/es/llm-prompt.md`](https://github.com/fastapi/fastapi/blob/master/docs/es/llm-prompt.md). + +/// tip | Совет + +Ознакомьтесь с документацией о [добавлении ревью pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-reviews), чтобы одобрить его или запросить изменения. + +/// + +#### Подпишитесь на уведомления для вашего языка + +Проверьте, существует ли [GitHub Discussion](https://github.com/fastapi/fastapi/discussions/categories/translations) для координации переводов на ваш язык. Вы можете подписаться на него, и когда появится новый pull request, требующий проверки, автоматический комментарий будет добавлен в обсуждение. + +Чтобы узнать двухбуквенный код для языка, который вы хотите перевести, вы можете воспользоваться таблицей [Список кодов ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). + +#### Запрос нового языка + +Допустим, вы хотите запросить переводы для языка, который еще не переведен, даже частично. Например, для латыни. + +* Первым шагом вам нужно найти еще двух человек, которые согласились бы проверять PR с переводами на этот язык вместе с вами. +* Как только наберется не менее трех человек, готовых взять на себя обязательство помогать поддерживать этот язык, вы можете переходить к следующим шагам. +* Создайте новое обсуждение, следуя шаблону. +* Отметьте двух других людей, которые будут помогать с языком, и попросите их подтвердить в обсуждении, что они готовы помогать. + +Как только в обсуждении появится несколько человек, команда FastAPI сможет его оценить и сделать перевод официальным. + +Затем документация будет автоматически переводиться с использованием LLM, а команда носителей языка сможет проверять перевод и помогать настраивать промпты для LLM. + +Когда появится новый перевод (например, если документация обновится или добавится новый раздел), в том же обсуждении будет добавлен комментарий со ссылкой на новый перевод для проверки. + +## Автоматизированный код и ИИ + +Мы приветствуем использование любых инструментов, которые вы хотите применять для своей работы и максимально эффективного участия в проекте, включая инструменты на основе ИИ (LLM) и другие. Тем не менее, вклад должен подразумевать осмысленное человеческое вмешательство, суждение, контекст и т.п. + +Если **человеческих усилий**, вложенных в PR (например, написание промптов для LLM), **меньше**, чем **усилий, которые нам потребуется затратить** на его **проверку**, пожалуйста, **не** отправляйте такой PR. + +Подумайте об этом так: мы и сами можем писать промпты для LLM или запускать автоматизированные инструменты, и это будет быстрее, чем проверять внешние PR. + +### Закрытие автоматизированных PR и PR, созданных с помощью ИИ + +Если мы увидим PR, которые выглядят как сгенерированные ИИ или автоматизированные подобным образом, мы пометим их и закроем. + +Тоже самое относится к комментариям и описаниям - пожалуйста, не копируйте содержимое, сгенерированное LLM. + +### Отказ в обслуживании человеческих усилий + +Использование автоматизированных инструментов и ИИ для отправки PR или комментариев, которые нам приходится тщательно проверять и обрабатывать, было бы равносильно [атаке типа «отказ в обслуживании»](https://en.wikipedia.org/wiki/Denial-of-service_attack) на наши человеческие усилия. + +Это потребовало бы очень мало усилий со стороны человека, отправляющего PR (один промпт для LLM), но порождало бы большой объем работы с нашей стороны (тщательная проверка кода). + +Пожалуйста, не делайте этого. + +Нам придется блокировать аккаунты, которые спамят нас повторяющимися автоматизированными PR или комментариями. + +### Используйте инструменты с умом + +Как говорил дядя Бен: + +
+С большой силой инструментами приходит большая ответственность. +
+ +Избегайте случайного вреда. + +У вас есть удивительные инструменты, используйте их с умом, чтобы помогать эффективно.