Содействие разработке

Добро пожаловать в разработку litegram!

litegram — это проект с открытым исходным кодом, и каждый может внести свой вклад любым возможным способом

Разработка

Перед внесением любых изменений в код фреймворка необходимо сделать форк проекта, клонировать проект на свой ПК и знать, как делать pull-request.

О том, как работать с pull-request, можно прочитать в документации GitHub

Так как этот проект написан на Python, вам потребуется установленный Python (рекомендуется использовать последние версии Python, но можно использовать любую версию, начиная с 3.13)

Использование virtualenv

Вы можете создать виртуальное окружение в каталоге, используя модуль venv (он должен быть предустановлен по умолчанию):

Это действие создаст каталог .venv с исполняемыми файлами Python, после чего вы сможете устанавливать пакеты в это изолированное окружение.

Активация окружения

Linux / macOS:

source .venv/bin/activate

Windows cmd

.\.venv\Scripts\activate

Windows PowerShell

.\.venv\Scripts\activate.ps1

Чтобы проверить, что все работает, используйте указанную команду; она должна показать версию pip и его расположение внутри изолированного окружения

pip -V

Также убедитесь, что в вас установлена последняя версия pip в вашем виртуальном окружении, чтобы избежать ошибок на следующих этапах:

python -m pip install --upgrade pip

Настройка проекта

После активации окружения установите litegram из исходников и его зависимости:

Linux / macOS:

pip install -e ."[dev,test,docs,fast,redis,mongo,proxy,i18n]"

Windows:

pip install -e .[dev,test,docs,fast,redis,mongo,proxy,i18n]

Это установит litegram в редактируемом режиме в ваше виртуальное окружение вместе со всеми зависимостями.

Альтернатива: Использование uv (современный подход)

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

Преимущества использования uv:

  • В 10-100 раз более быстрое разрешение зависимостей, чем у pip

  • Автоматическое управление виртуальными окружениями

  • Воспроизводимые сборки с помощью lock-файла

  • Единый инструмент для всех нужд управления пакетами

Установка uv:

Linux / macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Или через pip:

pip install uv

Настройка проекта с помощью uv:

Вместо ручного создания и активации виртуального окружения, uv делает это автоматически:

# Clone the repository
git clone https://github.com/litegram/litegram.git
cd litegram

# Install all dependencies (creates .venv automatically)
uv sync --all-extras --group dev --group test

# Install pre-commit hooks
uv run pre-commit install

Вот и все! Команда uv sync создает виртуальное окружение в .venv/, устанавливает все зависимости, включая дополнительные и инструменты разработки, и генерирует файл uv.lock для воспроизводимых сборок.

Запуск команд с помощью uv:

При использовании uv добавляйте префикс uv run к командам, чтобы выполнять их в управляемом окружении:

# Format code
uv run ruff format litegram tests scripts examples
uv run ruff check --fix litegram tests scripts examples

# Run tests
uv run pytest tests

# Run linting
uv run ruff check litegram examples
uv run ty check litegram

# Start documentation server
uv run sphinx-autobuild --watch litegram/ docs/ docs/_build/

Или используйте команды Makefile, которые теперь поддерживают uv:

make install    # Uses uv sync
make lint       # Uses uv run
make reformat   # Uses uv run
make test       # Uses uv run

Внесение изменений в код

На этом этапе вы можете вносить любые изменения в код: исправления, новые функции или эксперименты.

Форматирование кода (стиль кода)

Обратите внимание, что этот проект использует Ruff для форматирования и линтинга, поэтому вам следует придерживаться этого стиля кода. Чтобы убедиться, что вы все делаете правильно, давайте переформатируем код автоматически:

Используя традиционный подход:

ruff format litegram tests scripts examples
ruff check --fix litegram tests scripts examples

Или с помощью uv:

uv run ruff format litegram tests scripts examples
uv run ruff check --fix litegram tests scripts examples

Или просто используйте Makefile:

make reformat

Запуск тестов

Все изменения должны быть протестированы:

Используя традиционный подход:

pytest tests

Или с помощью uv:

uv run pytest tests

Или используйте Makefile:

make test

Также, если вы работаете с хранилищами Redis или MongoDB, вам нужно будет убедиться, что все работает с Redis и/или MongoDB:

Используя традиционный подход:

pytest --redis redis://<host>:<port>/<db> --mongo mongodb://<user>:<password>@<host>:<port> tests

Или с помощью uv:

uv run pytest --redis redis://<host>:<port>/<db> --mongo mongodb://<user>:<password>@<host>:<port> tests

Документация

Мы используем Sphinx для рендеринга документации на разных языках. Все исходники находятся в каталоге docs. Вы можете изменять их, а для тестирования запустить сервер предпросмотра в реальном времени:

Используя традиционный подход:

sphinx-autobuild --watch litegram/ docs/ docs/_build/

Или с помощью uv:

uv run --extra docs sphinx-autobuild --watch litegram/ docs/ docs/_build/

Или используйте Makefile:

make docs-serve
make docs-html

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

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

Перед началом давайте обновим все тексты:

Используя традиционный подход:

cd docs
make gettext
sphinx-intl update -p _build/gettext -l <language_code>

Или с помощью uv:

uv run --extra docs bash -c 'cd docs && make gettext'
uv run --extra docs bash -c 'cd docs && sphinx-intl update -p _build/gettext -l <language_code>'

Или используйте Makefile:

make docs-gettext

Замените <language_code> в примере ниже на код целевого языка. После этого вы сможете изменять тексты внутри docs/locale/<language_code>/LC_MESSAGES в виде файлов *.po, используя любой текстовый редактор или специализированные утилиты для GNU Gettext, например, poedit.

Чтобы просмотреть результаты:

Используя традиционный подход:

sphinx-autobuild --watch litegram/ docs/ docs/_build/ -D language=<language_code>

Или с помощью uv:

uv run --extra docs sphinx-autobuild --watch litegram/ docs/ docs/_build/ -D language=<language_code>

Описание изменений

Опишите ваши изменения в одном или нескольких предложениях, чтобы разработчики ботов знали, что изменилось в их любимом фреймворке: создайте файл <code>.<category>.rst и напишите описание.

<code> — это номер Issue или Pull-request. После релиза ссылка на эту задачу будет опубликована на странице Changelog.

<category> — это маркер категории изменений, он может быть одним из следующих:

  • feature — когда вы реализуете новую функцию

  • bugfix — когда вы исправляете ошибку

  • doc — когда вы улучшаете документацию

  • removal — когда вы удаляете что-то из фреймворка

  • misc — когда изменено что-то внутри ядра или конфигурации проекта

Если у вас возникли трудности с выбором категории, не стесняйтесь обращаться к основным разработчикам (Core-contributors) за помощью.

Завершение

После того как вы внесли все изменения, опубликуйте их в репозитории и создайте pull request, как упоминалось в начале статьи, и дождитесь обзора (review) этих изменений.

Поставьте звезду на GitHub

Вы можете поставить «звезду» репозиторию на GitHub — https://github.com/litegram/litegram (нажмите кнопку со звездой в правом верхнем углу)

Добавление звезд помогает другим людям легче находить этот проект и понимать, насколько он полезен.

Руководства

Вы можете писать руководства по разработке ботов на базе litegram и публиковать их на YouTube, Medium, GitHub Books, на платформах для курсов или любых других площадках, которые вам известны.

Это поможет большему количеству людей узнать о фреймворке и научиться им пользоваться.

Отвечайте на вопросы

Разработчики часто задают вопросы в наших чатах или на других платформах, таких как GitHub Discussions, StackOverflow и других. Не стесняйтесь отвечать на эти вопросы.

Финансирование

Разработка проекта бесплатна и не финансируется коммерческими организациями. Это моя личная инициатива (@RussianCheese), и я занимаюсь развитием проекта в свободное время.