Taigram: Начало работы
Всем привет!
На этой неделе мы объявили о начале работы над Open Source проектом Taigram, название которому, к слову, выбрали вы в опросе.
Для удобства отслеживания актуальных изменений по проекту рекомендуем заглядывать в тематическую рубрику у нас на сайте, где мы рассказываем о процессе разработки, объясняем наш выбор технологий, архитектуры и код.
Проектом занимаемся мы вдвоём: Иван и Виктор, а также с логотипом нам помог наш бессменный дизайнер Евгений. (Больше никто не захотел к нам присоединиться 😭)
Начнём мы, как водится, с самого начала...
Менеджер управления проектами Taiga.io
Любой проект начинается с продумывания работ, функционала и предстоящих задач. Это можно делать как в Telegram-переписке, блокноте, заметках Obsidian, так и использовать более профессиональные инструменты - менеджеры проектов.
Мы давно искали удобный (и, что немаловажно - бесплатный!) инструмент ведения проектов, который можно развернуть локально. В итоге остановились на Taiga.io.
Taiga.io - это бесплатный Open Source Self-Hosted менеджер управления проектами. Это означает, что это свободно распространяемое программное обеспечение, которое можно установить на свой собственный сервер, не беспокоясь о зависимости от какого-то крупного игрока.
Что не так с Тайгой и для чего нам нужен Taigram?
В тайге мы ведём наши проекты, включая процессы публикации статей на сайте.
Это оказалось действительно удобно, за исключением нескольких моментов и один из них - оповещения. Дело в том, что Тайга отправляет оповещения об изменении задачи только тем, кто назначен исполнителем и наблюдателем, и отправляет она их на Email, при условии, что у пользователя стоят соответствующие разрешения в его профиле. Согласитесь, это хоть и удобно (какие-никакие уведомления лучше, чем их полное отсутствие), но порой абсолютно не оперативно! Да и к тому же, вряд ли кто захочет "пачкать" свою почту.
Тогда появилась идея сделать Telegram-бота, который сможет отправлять уведомления в чат/тему чата. Мы приняли такое решение, в том числе из-за того, что Тайга предоставляет возможность подключить WebHook для отправки уведомлений и у отправляемых данных, достаточно простая структура и, в целом, этих данных достаточно - это важно. Это значит, что добавив на текущем этапе самый нужный, по нашему мнению, функционал - потом его можно дополнить. А если это можно дополнять и функционал, который мы добавим сейчас - самый нужный по нашему мнению, означает, что этого функционала может быть недостаточно для кого-то другого, под какие-то другие специфические задачи.
Если кому-то это нужно или кто-то посчитает, что знает чего сервису не хватает в настоящий момент - он сможет это дополнить. На наш взгляд это отличная идея и входящие данные для запуска работ над Open Source проектом.
Цель и функциональные требования
Цель: создание сервиса, который будет отправлять уведомления об обновлении списка задач и других событий из менеджера управления задачами Taiga в Telegram
Функциональные требования:
Настройка уведомлений через Telegram-бота:
Добавление/удаление администраторов бота;
Выбор чата/канала;
Добавление/удаление/изменение проектов;
Отображение списка проектов;
Отображение информации по проекту:
Форматирование, отправляемых сообщений.
Интеграция с Taiga через вебхуки.
Стек технологий
Бэкенд: Python, FastAPI, Aiogram;
Работа с данными: Taiga Webhooks, MongoDB, Redis;
Инфраструктура: Dynaconf, Pydantic.
Планирование проекта
Мы созвонились в нашем уютном Discord-сервере (присоединяйтесь, там мы регулярно работаем, общаемся или играем!) и открыв Obsidian, начали рисовать примерный план желаемого функционала. Спойлер: уже сейчас, спустя неделю с начала часть функционала изменено до неузнаваемости, но об этом в другой раз.
Найти схему можно в нашем проекте: https://tasks.pressanybutton.ru/project/taiga-webhook-telegram-notifier/task/5
Схема казалась небольшой, мы делали и куда более объёмные и даже посчитали "да чё там делать? За пару вечеров справимся"...
Закончив схему появились две первые задачи:
Организовать доску в Тайге
Сделать репозиторий.
Доской занялся Виктор, а я пошёл делать репозиторий на GitHub.
Организация доски
Не смотря на то, что у нас (как у Команды проекта "Код на салфетке", так и у меня лично (Виктора)) был опыт в подготовке как проектной, так и технической документации, но делать что-то, что изначально будет в открытом доступе значит, что у проекта есть дополнительные ограничения и "ответственность".
Мы совершенно не боимся признаться что какие-то вещи у нас получаются пока что не так хорошо или какие-то процессы могут быть выстроены как-то не так, как их можно было бы выстроить и именно поэтому мы решили, что будем вести разработку полностью открыто и все задачи вести также - открыто.
Шаг 1: Определение настроек проекта
Сперва нам было необходимо определиться с используемыми модулями в проектном менеджере для последующего масштабирования.
Почти сразу мы определили, что модуль "Канбана" нам не подходит, поскольку там невозможно создавать задачи в отрыве от пользовательских историй, следовательно создавать на каждую задачу пользовательскую историю "Дорожками" (не статусы) означает плодить сущности и терять контроль над "подзадачами".
Хочу повториться, что лично я не боюсь признавать свою неправоту и именно поэтому акцентирую внимание еще вот на чем: нам показалось странным, что мы не можем создавать "задачи" на канбане в отрыве от "пользовательских историй", потому что это лишает возможности оценить сложность задачи "в попугаях" (условная единица).
Вернемся к модулям, мы решили использовать:
Эпики: для стратегического планирования;
Скрам: для текущего управления спринтами;
Запросы: если у кого-то из команды или гостей проекта появится желание добавить какой-то функционал или сообщить о чем-то;
Вики: для создания первоначального хранилища базы знаний;
Шаг 2: Определение границ спринтов
Как было сказано ранее, вначале у нас сложилось впечатление, что мы действительно можем управиться за пару вечеров в силу функциональных требований и сложности структуры, предъявляемой к проекту, но все осложнилось тем, что проект - Open Source и следовательно его нужно постараться сделать пригодным для последующего масштабирования и поддержки.
Поэтому составили первоначальный план, который включал следующие этапы:
Подготовительная часть:
анализ задачи;
оформление всех функциональных хотелок в виде тезисов;
прогнозирование объема работ;
определение структуры проекта;
подготовка схем структуры проекта;
подготовка схем пользовательского пути;
Базовый функционал (этап основной разработки MVP):
подготовка структуры проекта;
инициализация проекта и первичная настройка виртуального окружения, инфраструктуры;
настройка CI/CD;
создание базовых классов, необходимых для реализации бизнес-логики;
валидация данных;
создание необходимых методов, для работы с текстовыми файлами (для последующей локализации);
Локализация:
русский язык;
английский язык;
Релиз GitHub Pages:
подготовка и настройка репозитория;
настройка CI/CD;
подготовка и оформление документации;
составление инструкций;
Шаг 3: Работа с доской
Как показала практика: никакая задача не заслуживает, чтобы к ней относились без должного внимания и трепета, а иначе разработка и конечный продукт может включать в себя больше хаоса и меньше структуры.
При определении глобальных спринтов и пользовательских историй мной были допущены ошибки в планировании и декомпозиции задач, в следствие чего небольшие задачи, которые были взяты в разработку, выросли в полноценные, тесно связанные модули и даже пакеты. Ваня, в силу опыта, с поставленными задачами справлялся лучше - его комиты как правило включали изолированные задачи и выполнялись быстрее.
По моим наблюдениям, регулярное обновление информации по статусам задачи держит команду "в тонусе" и позволяет придерживаться "единого вектора" в разработке.
Откровениями "о взлетах и падениях" мы поделимся в последующих статьях, но считаем, что о публичном проекте, нужно говорить честно и открыто - этим объясняется существование этого подраздела.
Технологический стек
Помимо функциональных требований, мы обсудили и технологический стек для проекта.
В качестве пакетного менеджера мы выбрали набирающий популярность uv. Как раз в новой версии PyCharm добавили его нативную поддержку. Честно, пока не заметил за ним каких-то преимуществ перед "надёжным как Швейцарские часы" Poetry, но вдруг он раскроется в будущем?
Для обработки обновлений Telegram и приёма оповещений из Тайги по WebHook был выбран микрофреймворк FastAPI. Полагаю, что он не нуждается в представлении: быстрый, надёжный и достаточно гибкий.
Сердцем Telegram-бота является aiogram. По нашему мнению - самый лучший фреймворк для написания ботов.
Поскольку в проекте не подразумевается большого количества данных для хранения, мы выбрали в качестве базы данных MongoDB с асинхронной библиотекой Motor.
Для хранения состояний и временных данных отлично подойдёт Redis. Это такой легковесный брокер сообщений / база данных.
Также, в проект был подключен pre-commit, позволяющий запускать линтеры перед коммитом. Он нужен для того, чтобы стиль кода всех разработчиков совпадал во всём проекте, ну и заодно он проверяет, что нет неиспользуемых импортов/переменных, некорректных вызовов и много, что ещё.
Создание репозитория
Создать репозиторий - буквально меньше минуты, но на пустом репозитории далеко не уедешь, да и показывать его кому-то стыдно. Поэтому для него необходимо было создать начальный проект в uv, а также ряд организационных файлов.
Проект в uv создаётся примерно также, как и в Poetry. Прописываем команду uv init taiga_wh_notifier. В результате создастся директория в которой будет основа проекта, инициализированный git и .venv. Удобно.
Перейдя в директорию сразу добавляем origin репозитория на гитхаб.
Далее нужно было создать основные файлы:
README.md - лицо всего репозитория. На данный момент оно практически пустое, мы определили основные разделы ридми файла, но пока не будет относительно рабочего функционала, заполнять ридми рано.
CONTRIBUTING.md - в этом файле описывает процесс по которому любой желающий сможет развернуть локальную версию проекта и вносить необходимые правки в код.
STYLEGUIDE.md - в этом файле описываются принципы и примеры стиля кода которому мы придерживаемся. Ничего сверхъестественного, но наличие этого файла поможет новым участникам проекта быть с нами "на одной волне".
Всё это мы писали вместе на основе нашего виденья проектов. В будущем содержимое файлов будет расширено и приобретёт полноценный вид.
В конце коммит и пуш. Первая задача закрыта, на очереди ещё сотня...
Настройка репозитория на GitHub
Проект создан, запушен, но не хватает одной маленькой детали - настройки репозитория на GitHub.
Что я имею ввиду? У нас есть главная ветка репозитория main и по умолчанию, каждый может в неё пушить, что является критической уязвимостью в целостности всего проекта. Да, можно откатывать коммиты и прочее, но всё это дополнительные и далеко не самые приятные действия.
Что нам нужно было сделать, дабы предотвратить хаос? Мы разработали правила работы с репозиторием!
Правила работы
Если над проектом работает больше одного человека - хаос неизбежен. Кто-то забудет сделать пулл актуального состояния, кто-то другой будет одновременно с третьим работать над одним файлом и вызовет конфликт веток. Что мы сделали для решения этих проблем?
Ветка main заблокирована от всех пушей, даже от имени создателя репозитория. Это решает проблему "случайного пуша в мейн", когда участник команды написал код, но забыл сменить ветку.
Участники работают каждый в своей ветке, при это ветка не постоянная, а создаётся исключительно под задачу, после чего удаляется. Это позволяет определить по названию ветки к какой задаче на доске она относится, а не выяснять по коммитам, над какой же задачей работал участник.
Для того, чтобы внести изменения в main-ветку, необходимо создать pull request. При этом, для того, чтобы сделать "мерж в мейн", необходимо одобрение минимум одного другого участника. Таким образом, в main-ветку не попадёт ничего случайно, только после код-ревью и одобрения.
Мы не сразу "притёрлись" с этой системой, так как каждый привык работать в одиночку. Однако, спустя время осознали её удобство, а когда разобрались, как всё это делать не выходя из PyCharm, стало вообще прекрасно.
Приглашение к разработке:
Если вас заинтересовал проект и вы считаете, что могли бы принести пользу в разработке, а также, если после прочтения этой статьи или ознакомления с материалами проекта вы пришли к выводу, что вам точно известно чего не хватает этому продукту и вы знаете как его можно улучшить - мы приглашаем присоединиться к проекту и принять участие в разработке!
Для этого свяжитесь с нами
Заключение
Это только самое начало, дальше начали создавать задачи и непосредственно писать код, о чём вы узнаете в следующей части.
Ссылки, касающиеся проекта: