Сприяння розробці

Ласкаво просимо зробити свій внесок у aiogram!

aiogram є проєктом з відкритим вихідним кодом, і будь-хто може зробити свій внесок у будь-який можливий спосіб

Розробка

Перш ніж вносити будь-які зміни в код фреймворка, потрібно створити форк проєкту, клонувати проєкт на свій комп’ютер і розуміти, як робити запит на витяг (pull-request).

Як працювати із запитами на витяг (pull-request), можна прочитати в документації GitHub

Оскільки цей проєкт написаний на Python, вам потрібно встановити Python (рекомендується використовувати останні версії Python, але можна використовувати будь-яку версію, починаючи з 3.8)

Використовуйте 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

Налаштування проєкту

Після активації середовища встановіть aiogram із вихідних кодів разом із їх залежностями.

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]

Це встановить aiogram у режимі редагування у ваше віртуальне середовище та всі залежності.

Alternative: Using uv (Modern Approach)

As an alternative to the traditional pip and venv workflow, you can use uv - a modern, fast Python package manager that handles virtual environments, dependency resolution, and package installation.

Benefits of using uv:

  • 10-100x faster dependency resolution than pip

  • Automatic virtual environment management

  • Reproducible builds with lockfile

  • Single tool for all package management needs

Installing 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"

Or using pip:

pip install uv

Setup project with uv:

Instead of manually creating and activating a virtual environment, uv handles this automatically:

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

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

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

That’s it! The uv sync command creates a virtual environment in .venv/, installs all dependencies including optional extras and development tools, and generates a uv.lock file for reproducible builds.

Running commands with uv:

When using uv, prefix commands with uv run to execute them in the managed environment:

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

# Run tests
uv run pytest tests

# Run linting
uv run ruff check aiogram examples
uv run mypy aiogram

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

Or use the Makefile commands which now support uv:

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

Внесення змін у код

На цьому етапі ви можете вносити будь-які зміни у код, які бажаєте, це можуть бути виправлення, впровадження нових функцій або експерименти.

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

Note that this project uses Ruff for formatting and linting, so you should follow that code-style. To be sure you’re correctly doing this, let’s reformat the code automatically:

Using traditional approach:

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

Or with uv:

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

Or simply use Makefile:

make reformat

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

Всі зміни повинні бути протестовані:

Using traditional approach:

pytest tests

Or with uv:

uv run pytest tests

Or use Makefile:

make test

Крім того, якщо ви працюєте з Redis-сховищем і/або сховищем MongoDB, вам потрібно протестувати, чи все працює з Redis і/або MongoDB:

Using traditional approach:

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

Or with uv:

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

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

Ми використовуємо Sphinx для створення документації різними мовами. Всі вихідні файли знаходяться в каталозі docs. Ви можете змінювати джерела та тестувати їх, запустивши сервер попереднього перегляду, щоб побачити, що ви робите:

Using traditional approach:

sphinx-autobuild --watch aiogram/ docs/ docs/_build/

Or with uv:

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

Or use Makefile:

make docs-serve

Переклади документації

Переклад документації є дуже важливим і не може бути виконаний без допомоги спільноти зі всього світу, тому ми запрошуємо вас перекладати документацію різними мовами.

Перш ніж почати, оновіть усі тексти:

Using traditional approach:

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

Or with 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>'

Or use Makefile:

make docs-gettext

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

Щоб переглянути результати:

Using traditional approach:

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

Or with uv:

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

Опишіть зміни

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

<code> — це номер issue або запиту на витяг (pull-request). Після релізу посилання на цей issue буде опубліковано на сторінці Changelog.

<category> — це маркер категорії змін, і це може бути одне з наступного:

  • feature — якщо ви впроваджуєте нову функцію

  • bugfix — якщо ви виправляєте помилку

  • doc — якщо ви покращуєте документацію

  • removal — якщо ви видаляєте щось із фреймворку

  • misc — якщо ви змінили щось усередині ядра або конфігурації проєкту

Якщо у вас виникли труднощі з вибором категорії, не соромтеся звертатися до основних контриб’юторів за допомогою.

Завершення

Після того, як ви внесли всі зміни, опублікуйте їх у репозиторії і створіть запит на витяг, як зазначено в початку статті, і зачекайте на перегляд цих змін.

Зірка на GitHub

Ви можете «зіркувати» репозиторій на GitHub -https://github.com/aiogram/aiogram (натисніть кнопку зірки в правому верхньому куті)

Додавання зірок полегшує іншим людям знаходження цього проекту і розуміння того, наскільки він корисний.

Інструкції

Ви можете написати посібники, як розробляти ботів на основі aiogram і публікувати їх на YouTube, Medium, GitHub Books, будь-якій платформі курсів або на будь-якій іншій платформі, яку ви знаєте.

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

Запитання

Розробники завжди задають питання в наших чатах або на інших платформах, таких як GitHub Discussions, StackOverflow та інших, не соромтеся відповідати на ці питання.

Фінансова підтримка

Розробка проекту є безкоштовною і не фінансується комерційними організаціями, це моя особиста ініціатива (@JRootJunior) і я займаюся розробкою проекту у вільний час.

Тож, якщо ви хочете фінансово підтримати проект, або, наприклад, купити мені піцу чи пиво, ви можете зробити це на OpenCollective.