Taigram: Начало работы

Всем привет!

На этой неделе мы объявили о начале работы над Open Source проектом Taigram, название которому, к слову, выбрали вы в опросе.

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

Проектом занимаемся мы вдвоём: Иван и Виктор, а также с логотипом нам помог наш бессменный дизайнер Евгений. (Больше никто не захотел к нам присоединиться 😭)

Начнём мы, как водится, с самого начала...

Менеджер управления проектами Taiga.io

Любой проект начинается с продумывания работ, функционала и предстоящих задач. Это можно делать как в Telegram-переписке, блокноте, заметках Obsidian, так и использовать более профессиональные инструменты - менеджеры проектов.

Мы давно искали удобный (и, что немаловажно - бесплатный!) инструмент ведения проектов, который можно развернуть локально. В итоге остановились на Taiga.io.

Taiga.io - это бесплатный Open Source Self-Hosted менеджер управления проектами. Это означает, что это свободно распространяемое программное обеспечение, которое можно установить на свой собственный сервер, не беспокоясь о зависимости от какого-то крупного игрока.

Что не так с Тайгой и для чего нам нужен Taigram?

В тайге мы ведём наши проекты, включая процессы публикации статей на сайте.

Это оказалось действительно удобно, за исключением нескольких моментов и один из них - оповещения. Дело в том, что Тайга отправляет оповещения об изменении задачи только тем, кто назначен исполнителем и наблюдателем, и отправляет она их на Email, при условии, что у пользователя стоят соответствующие разрешения в его профиле. Согласитесь, это хоть и удобно (какие-никакие уведомления лучше, чем их полное отсутствие), но порой абсолютно не оперативно! Да и к тому же, вряд ли кто захочет "пачкать" свою почту.

Тогда появилась идея сделать Telegram-бота, который сможет отправлять уведомления в чат/тему чата. Мы приняли такое решение, в том числе из-за того, что Тайга предоставляет возможность подключить WebHook для отправки уведомлений и у отправляемых данных, достаточно простая структура и, в целом, этих данных достаточно - это важно. Это значит, что добавив на текущем этапе самый нужный, по нашему мнению, функционал - потом его можно дополнить. А если это можно дополнять и функционал, который мы добавим сейчас - самый нужный по нашему мнению, означает, что этого функционала может быть недостаточно для кого-то другого, под какие-то другие специфические задачи.

Если кому-то это нужно или кто-то посчитает, что знает чего сервису не хватает в настоящий момент - он сможет это дополнить. На наш взгляд это отличная идея и входящие данные для запуска работ над Open Source проектом.

Цель и функциональные требования

1. Цель: создание сервиса, который будет отправлять уведомления об обновлении списка задач и других событий из менеджера управления задачами Taiga в Telegram
2. Функциональные требования:
   • Настройка уведомлений через Telegram-бота:
     • Добавление/удаление администраторов бота;
     • Выбор чата/канала;
     • Добавление/удаление/изменение проектов;
     • Отображение списка проектов;
     • Отображение информации по проекту:
     • Форматирование, отправляемых сообщений.
   • Интеграция с Taiga через вебхуки.
3. Стек технологий
   • Бэкенд: 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 и по умолчанию, каждый может в неё пушить, что является критической уязвимостью в целостности всего проекта. Да, можно откатывать коммиты и прочее, но всё это дополнительные и далеко не самые приятные действия.

Что нам нужно было сделать, дабы предотвратить хаос? Мы разработали правила работы с репозиторием!

Правила работы

Если над проектом работает больше одного человека - хаос неизбежен. Кто-то забудет сделать пулл актуального состояния, кто-то другой будет одновременно с третьим работать над одним файлом и вызовет конфликт веток. Что мы сделали для решения этих проблем?

1. Ветка main заблокирована от всех пушей, даже от имени создателя репозитория. Это решает проблему "случайного пуша в мейн", когда участник команды написал код, но забыл сменить ветку.
2. Участники работают каждый в своей ветке, при это ветка не постоянная, а создаётся исключительно под задачу, после чего удаляется. Это позволяет определить по названию ветки к какой задаче на доске она относится, а не выяснять по коммитам, над какой же задачей работал участник.
3. Для того, чтобы внести изменения в main-ветку, необходимо создать pull request. При этом, для того, чтобы сделать "мерж в мейн", необходимо одобрение минимум одного другого участника. Таким образом, в main-ветку не попадёт ничего случайно, только после код-ревью и одобрения.

Мы не сразу "притёрлись" с этой системой, так как каждый привык работать в одиночку. Однако, спустя время осознали её удобство, а когда разобрались, как всё это делать не выходя из PyCharm, стало вообще прекрасно.

Приглашение к разработке:

Если вас заинтересовал проект и вы считаете, что могли бы принести пользу в разработке, а также, если после прочтения этой статьи или ознакомления с материалами проекта вы пришли к выводу, что вам точно известно чего не хватает этому продукту и вы знаете как его можно улучшить - мы приглашаем присоединиться к проекту и принять участие в разработке!

Для этого свяжитесь с нами

Заключение

Это только самое начало, дальше начали создавать задачи и непосредственно писать код, о чём вы узнаете в следующей части.

Ссылки, касающиеся проекта:

1. GitHub
2. Доска разработки в Taiga
3. Рубрика на сайте