Gitlab и Specification-as-Code: Спасение от хаоса и кофеиновой зависимости
Введение
Для компании SimpleOne управление спецификациями требований было настоящей головной болью, требующей унификации подходов и учета потребностей разных команд. Мы стояли перед выбором: сделать свое решение для управления требованиями и сбора спецификаций или попробовать уже существующие практики. Концепция DocOps привлекла внимание тем, что помогает стандартизировать инструменты и навести порядок в хранении артефактов. В этой статье мы расскажем, как внедрили подход на основе docs as code, какие преимущества получили и какие трудности преодолели на пути.
О компании
SimpleOne — российский разработчик решений для автоматизации бизнес-процессов на базе собственной low-code платформы. Платформа помогает автоматизировать работу IT, HR, АХО и других подразделений компании, основываясь на лучших практиках предоставления сервисов (ITIL, VeriSM). Наши решения ориентированы на корпоративных и государственных клиентов, стремящихся к повышению эффективности и цифровой трансформации бизнеса.
Об авторах
Дарья Васьковская — аналитик в SimpleOne, экс-Яндекс. Участвую в запуске новых продуктов и объединяю опыт из разных сфер для поиска лучших решений
Сергей Бакин — руководитель направления бизнес-системного анализа SimpleOne, CBAP, более 12 лет опыта в IT.
Предыстория
До внедрения Doc as Code мы управляли требованиями через Google Docs, создавая спецификации для элементов бэклога, которые затем попадали в очередь задач продуктовых команд. Это приводило к проблемам:
Отсутствие версионирования: Трудно было отслеживать изменения и возвращаться к предыдущим версиям спецификаций.
Трудности в совместной работе: Было трудно сообщать о конкретных изменениях в спецификации с течением времени. Процесс ревью спецификаций был муторным и синхронным.
Мы решили провести эксперимент и создать свой подход — Spec-as-Code. Этот подход вырос из идеи Docs-as-Code, которая активно используется техническими писателями из таких компаний как Google, Microsoft, Twitter, Т-Банк, Ozon и другими для управления документацией как кодом.
Преимущества Spec-as-Code: Почему вам стоит задуматься об этом подходе
Версионирование:
Возможность отслеживать изменения и возвращаться к предыдущим версиям спецификаций. Например, если в новой версии спецификации оказалось ошибочное требование, мы можем быстро вернуться к предыдущей версии без потерь.
Прозрачность и контроль:
Использование Git и платформы GitLab обеспечивает прозрачность процессов. Участники команды могут асинхронно просматривать и комментировать итеративные изменения, что улучшает качество спецификаций и кода.
Гибкие инструменты использования GitLab:
GitLab предоставляет широкий набор инструментов для работы с проектами, что создает потенциал для роста и дальнейшего развития. Например, использование пайплайнов для автоматизации тестирования и развертывания спецификаций, широкий выбор готовых интеграций с такими сервисами, как Telegram, Notion, Jira, Google Docs, а также возможности для мониторинга и аналитики.
Сейчас мы активно экспериментируем над автоматизированным тестированием спецификаций, расскажем об успехах в будущих статьях!
Совместная работа:
Простота и безопасность работы в команде с возможностью параллельного редактирования. Аналитики, разработчики и техписы могут одновременно вносить изменения, не опасаясь конфликтов. Например, пока один аналитик работает над спецификацией, другой может заниматься анализом требований, а разработчик уже начинает писать код на основе текущей версии. Влитие веток друг в друга позволяет специалистам сообщать, когда они закончили свою часть работы, и отправлять чистовую версию на проверку в чужую ветку при помощи merge request (см. «Диаграмма ветвления git для команды разработки») .
Интеграция с процессами разработки:
Спецификации могут находиться рядом с кодом, что облегчает их использование и обновление в процессе разработки. Это позволяет разработчикам и ревьюерам сразу видеть требования к функциональности прямо в репозитории, не переключаясь между различными системами.
Единая точка правды:
Все спецификации хранятся в репозиториях разрабатываемых продуктов, что упрощает доступ и поиск необходимой информации для всех членов команды.
БОльшая независимость от сторонних инструментов:
Хранение данных и документации на собственных серверах или в частных облаках снижает риски, связанные с блокировками и санкциями, обеспечивая полный контроль и защиту информации.
Процесс работы с ветками
Мы разработали однозначный процесс работы с ветками в Git, чтобы обеспечить явное разделение обязанностей и минимизировать возможность конфликтов. Вот как это работает:
Шаг 1: Создание ветки для каждой задачи (Story)
При переходе задачи в статус Backlog (to do) аналитик создает ветку в нашем репозитории. Название ветки должно соответствовать номеру и теме задачи, например, STR000000000-new-feature. Мы решили включать название задачи в имя ветки, чтобы аналитикам было проще искать нужную ветку. Если идет восполнение технического долга и участвует только аналитик, можно создать ветку по модулю и отводить её сразу же от dev.
Шаг 2: Создание подветок для спецификаций
От основной ветки создаются подветки для спецификаций (например, STR000000000-spec-new-feature). Аналитик работает над спецификацией только в этой ветке.
Шаг 3: Создание подветок для текстов и переводов
При необходимости, создаются ветки для текстов и переводов (например, STR000000000-text-new-feature). Технический писатель работает над текстами в этой ветке. Каждая подветка предназначена для определенного этапа работы: задачи, спецификации, тексты. Это позволяет различным специалистам работать параллельно, не мешая друг другу. Также это позволяет специалистам сообщать, когда они закончили свою часть работы, и отправлять чистовую версию на проверку в чужую ветку при помощи merge request.
Шаг 4: Создание спецификации
Спецификация создается аналитиком, когда задача находится в статусе Backlog (to do). По окончании этого этапа спецификация должна содержать все требования и связи с элементами бэклога. Для перехода в Backlog (done) создается merge request в STR000000000-text-new-feature и проходит проверки.
Шаг 5: Проверка и вливание изменений
Создается Review Task в нашей системе SimpleOne для проверки merge request командой (Product Owner для проверки бизнес-требований, тестировщик для написания тест плана, разработчик). Тимлида назначают ответственным за проверку, поскольку он лучше всех знает архитектуру и может оценить реализуемость изменений. Это также делает процесс более асинхронным, что хорошо для командной работы (исследования показывают, что асинхронная работа повышает продуктивность и удовлетворенность сотрудников). Тимлид вливает MR после получения «ОК» от всех проверяющих.
Шаг 6: Переход в статус Backlog (done)
После влития в STR000000000-text-new-feature, задача переходит на стадию Backlog (done). Разработчик видит чистовую и проверенную спецификацию в своей ветке и может начать работу только над тем, что есть в его ветке. Тестировщик может начинать работу над тест-планом. Аналитик может вносить изменения в своей «черновой» ветке.
Схема работы
Если изменения в спецификации потребуются на более поздних этапах, создается новый Review Task и проводится повторное ревью командой. Так мы уверены том, что изменения в спецификации не останутся без внимания: Product Owner проверит бизнес-требования, тестировщик обновит тест-план, разработчик внесет изменения в код.
Решение merge конфликтов
В случае возникновения merge конфликтов, вопрос решается синхронно на встрече или асинхронно по инструкции, чтобы минимизировать задержки в разработке.
Результаты эксперимента
К этому моменту, полгода как мы закончили эксперимент и используем этот подход в повседневной деятельности. Результатыь:
Мы улучшили инструментарий аналитиков, добавив инструменты разработчиков, что повысило общий уровень их квалификации.
Адаптация к новым инструментам прошла быстрее, чем мы ожидали, и заняла менее месяца для сотрудников без опыта работы с GitLab.
Cократилось время на проверку требований со стороны команды разработки — теперь ревью выполняется на 40% быстрее в среднем.
Как со стороны разработки, так и со стороны QA возросло участие в обсуждении спецификаций и контроле качества требований.
Уменьшилось количество дефектов в продукте благодаря тому, что тестировщик теперь пишет тест-планы и проверяет продукт на основе спецификаций, в которых учитываются edge cases всей командой.
Мы привлекли технических писателей к процессу работы в Git, что позволило нам более удобно проверять текстовые материалы.
Учитывая успешные результаты эксперимента, следующим логичным шагом в развитии подхода будет внедрение AI-инструментов для разработки и управления спецификациями требований. Например, это может включать автоматическую проверку корректности формулировок, пунктуации, орфографии и выявление противоречий с другой информацией о продукте.
Высказывайтесь и присоединяйтесь к обсуждению в комментариях! Расскажите, как вы управляете спецификациями в проектах. Возможно, ваш опыт поможет другим читателям найти лучшие решения для своих команд. Не забудьте подписаться на наш блог, чтобы не пропустить новые статьи о передовых практиках разработки.
В одной из следующих статей расскажем о темплейтах, которые мы используем для хранения спецификаций.
Habrahabr.ru прочитано 1118 раз
