argoarsiks
4 months ago
1 changed files with 260 additions and 0 deletions
@ -0,0 +1,260 @@ |
|||||
|
# Разработка - Вклад |
||||
|
|
||||
|
Для начала вам, возможно, захочется ознакомиться с основными способами [помочь проекту FastAPI и получить помощь](help-fastapi.md). |
||||
|
|
||||
|
## Разработка |
||||
|
|
||||
|
Если вы уже клонировали [репозиторий fastapi](https://github.com/fastapi/fastapi) и вы хотите глубоко погрузиться в код, вот несколько рекомендаций по настройке вашего окружения. |
||||
|
|
||||
|
### Установка зависимостей |
||||
|
|
||||
|
Создайте виртуальное окружение и установите необходимые пакеты с помощью [uv](https://github.com/astral-sh/uv): |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ uv sync --extra all |
||||
|
|
||||
|
---> 100% |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Это установит все зависимости и вашу локальную версию FastAPI в локальное окружение. |
||||
|
|
||||
|
### Использование вашей локальной версии FastAPI |
||||
|
|
||||
|
Если вы создадите Python-файл, который импортирует и использует FastAPI, и запустите его с помощью Python из вашего локального окружения, он будет использовать клонированный вами локальный исходный код FastAPI. |
||||
|
|
||||
|
И если вы обновите этот локальной исходный код FastAPI, то при повторном запуске того же Python-файла будет использоваться свежая версия FastAPI, которую вы только что отредактировали. |
||||
|
|
||||
|
Таким образом, вам не нужно "устанавливать" вашу локальную версию, чтобы иметь возможность тестировать каждое изменение. |
||||
|
|
||||
|
/// note | Технические детали |
||||
|
|
||||
|
Это происходит только в том случае, если вы устанавливаете зависимость с помощью `uv sync --extra all`, а не запускаете `pip install fastapi` напрямую. |
||||
|
|
||||
|
Это связанно с тем, что `uv sync --extra all` по умолчанию устанавливает локальную версию FastAPI в "редактируемом (editable)" режиме. |
||||
|
|
||||
|
/// |
||||
|
|
||||
|
### Форматирование кода |
||||
|
|
||||
|
Существует скрипт, который вы можете запустить для форматирования и очистки всего вашего кода: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ bash scripts/format.sh |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Он также автоматически отсортирует все ваши импорты. |
||||
|
|
||||
|
## Тестирование |
||||
|
|
||||
|
Существует скрипт, который вы можете запустить локально для тестирования всего кода и создания отчетов о покрытии в формате HTML: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ bash scripts/test-cov-html.sh |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Эта команда создает директорию `./htmlcov/`. Если вы откроете файл `./htmlcov/index.html` в вашем браузере, вы сможете в интерактивном режиме изучить участки кода, которые покрыты тестами, если какие-то участки пропущены. |
||||
|
|
||||
|
## Документация |
||||
|
|
||||
|
Сначала убедитесь, что вы настроили свое окружение, как описано выше - это установит все необходимые зависимости. |
||||
|
|
||||
|
### Документация в реальном времени |
||||
|
|
||||
|
Во время локальной разработки существует скрипт, которые собирает сайт и отслеживает любые изменения с автоматической перезагрузкой. |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ python ./scripts/docs.py live |
||||
|
|
||||
|
<span style="color: green;">[INFO]</span> Serving on http://127.0.0.1:8008 |
||||
|
<span style="color: green;">[INFO]</span> Start watching changes |
||||
|
<span style="color: green;">[INFO]</span> Start detecting changes |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Он запустит документацию по адресу `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, вы можете установить автодополнение с помощью: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ typer --install-completion |
||||
|
|
||||
|
zsh completion installed in /home/user/.bashrc. |
||||
|
Completion will take effect once you restart the terminal. |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
### Структура документации |
||||
|
|
||||
|
Документация использует [MkDocs](https://www.mkdocs.org/). |
||||
|
|
||||
|
А также есть дополнительные инструменты/скрипты для работы с переводами в `./scripts/docs.py`. |
||||
|
|
||||
|
/// tip | Совет |
||||
|
|
||||
|
Вам не нужно изучать код в `./scripts/docs.py`, вы просто используете его из командной строки. |
||||
|
|
||||
|
/// |
||||
|
|
||||
|
Вся документация находится в формате Markdown в директории `./docs/en/`. |
||||
|
|
||||
|
Многие из руководств содержат блоки кода. |
||||
|
|
||||
|
В большинстве случаев эти блоки кода представляют собой полноценные приложения, которые можно запускать как есть. |
||||
|
|
||||
|
На самом деле эти блоки кода не написаны внутри Markdown, они представляют собой Python-файлы в директории `./docs_src/`. |
||||
|
|
||||
|
И эти Python-файлы включаются/внедряются в документацию при генерации сайта. |
||||
|
|
||||
|
### Документация для тестов |
||||
|
|
||||
|
Большинство тестов на самом деле выполняются на примерах исходных файлов из документации. |
||||
|
|
||||
|
Это помогает убедиться в том, что: |
||||
|
|
||||
|
* Документация актуальна. |
||||
|
* Примеры из документации можно запускать как есть. |
||||
|
* Большинство функций покрыто документацией, что подтверждается покрытием тестами. |
||||
|
|
||||
|
#### Приложения и документация одновременно |
||||
|
|
||||
|
Если вы запускаете примеры, например: |
||||
|
|
||||
|
<div class="termy"> |
||||
|
|
||||
|
```console |
||||
|
$ fastapi dev tutorial001.py |
||||
|
|
||||
|
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
||||
|
``` |
||||
|
|
||||
|
</div> |
||||
|
|
||||
|
Поскольку 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 или комментариями. |
||||
|
|
||||
|
### Используйте инструменты с умом |
||||
|
|
||||
|
Как говорил дядя Бен: |
||||
|
|
||||
|
<blockquote> |
||||
|
С большой <strike>силой</strike> <strong>инструментами</strong> приходит большая ответственность. |
||||
|
</blockquote> |
||||
|
|
||||
|
Избегайте случайного вреда. |
||||
|
|
||||
|
У вас есть удивительные инструменты, используйте их с умом, чтобы помогать эффективно. |
||||
Loading…
Reference in new issue