что такое релиз ноутс
Правила написания Release Notes
Release Notes – это документ, описывающий изменения между выпускаемой и предыдущей версиями программного продукта. Адресатом данного документа в первую очередь являются технические специалисты клиента, которые занимаются обслуживанием продукта, интеграторы и команды внедрения. Поэтому документ в первую очередь должен содержать полезную техническую информацию, а не маркетинговые лозунги.
Состав документа
В некоторых конторах в качестве Release notes наружу выдают маркетинговый булшит, а реальное техническое содержание оставляют только для внутреннего читателя. Это косвенно указывает на то, что в продукте много проблем, а производитель ПО вместо их исправления скрывает их. В обратной ситуации, когда принята политика открытости перед пользователем, и его честно информируют о всех косяках в софте, то пользователь будет более лоялен к производителю ПО. В качестве дополнительного бонуса прозрачность мотивирует делать качественные продукты. Стыдно ведь публично писать о своей криворукости.
Сам документ состоит из следующих разделов:
Краткое описание продукта
Несколько предложений или пара абзацев о продукте. Служит для того, чтобы человек, которому в руки попал документ, мог погрузиться в контекст. Иначе без введения на него сразу будет вывален список нового функционала и багов. Не нужно сразу пугать людей.
Что нового
Изменение функциональности относительно прошлой версии. Перечисление основных изменений с их кратким описанием. Цель раздела — объяснить пользователю зачем ему тратить своё время и переходить на новую версию.
Исправленные ошибки
Список исправленных ошибок относительно предыдущей версии. Как и предыдущий раздел, этот тоже стимулирует пользователя на апгрейд. Обязательно описать исправленные проблемы, на которые жаловались клиенты и которые были заявлены как known issues в прошлых версиях. Крайне желательно описать те серьезные проблемы, с которыми пользователь мог столкнуться в прошлых версиях, но жалоб на них не поступало. Отсутствие жалоб вовсе не означает, что с ними никто сталкивался. Возможно люди мучились, но у них не хватило сил пробиться через поддержку.
Включать в этот список все содержимое баг трекера не нужно:
Удобно указывать ID проблемы, для удобства истории ошибки.
Список известных проблем или known issues
Если у вас нет known issues – значит никто не тестировал продукт.
Приводим список известных проблем (багов). Идеально, если в нем содержатся все актуальные баги для данной версии. Если их слишком много, то выбираем наиболее критичные для пользователя. Для каждого бага нужно указывать:
Есть соблазн написать в этот раздел поменьше, чтобы не пугать клиентов. Всех, кто так считает, можно отправить к рассказу Драгунского «Тайное становится явным». Если клиенты действительно используют продукт, то все равно они найдут все эти баги, в дополнение у них еще появятся вопросы к качеству тестирования продукта производителем. А так вы честно демонстрируете открытость клиентам и сразу выдаете список woraround’ов, снижая затраты на поддержку.
Не стоит забывать и про мотивационную составляющую. Если люди работают в условиях прозрачности, то они склонны делать свою работу более качественно, краснеть никто не любит.
Технические ограничения
Любое ПО имеет технические ограничения. Ваш сервер позволяет работать одновременно 10 пользователям? В базу можно сделать только 10000 записей? UI рассчитан только на Full HD? Напишите об этом.
Системные требования
В данном разделе все понятно: минимальные и рекомендуемые требования по железу, поддерживаемые операционные системы, требуемый сторонний софт.
Если параметры железа зависят от сценариев использования продукта, например, от количества пользователей, сложности вычислений, количества данных в базе, то хорошо сделать sizing guide. Это таблица в стиле: если ожидается такая нагрузка, то рекомендуется такое железо.
Особенности обновления с прошлой версии.
Апдейт не всегда проходит гладко. А потеря данных пользователя вообще караул. Лучше сразу предупредить о возможных проблемах.
Кто пишет документ
Все новости сайта в телеграм канале: @pmlife_ru
Странное искусство составления пояснений к релизу приложений
Если у вас есть iPhone, зайдите в App Store и откройте обновления. Вы увидите пояснительные записки, описывающие изменения, сделанные разработчиками в самых новых версиях приложений вашего телефона. По большей части они довольно скучные:
Но иногда примечание выделяется. Недавно просматривая собственные оббновления, я наткнулся на одно из них, написанное для транспортного приложения под названием Transit, которое я часто использую в Нью-Йорке.
Только вы решили, что мы лишь багов мочим. Только вы подумали: «Давненько я не получал сообщений от Transit». Только вы подумали о том, что самые ваши глубинные и тёмные фантазии, связанные с Transit, нереализуемы. Как мы внезапно тут. Сюрприз, сюрприз. Пришло время для Transit 4.3
* включается немецкое техно, от которого быстрее бьётся сердце *
тунц-тунц-тунц-тунц-тунц-тунц-тунц…
Фанаты Uber. Мы знаем, что вы есть. Вы ездите по городу, каждую ночь, на одной пятизвёздочной машине за другой. Специально для тех случаев, когда вы решите сделать что-то необычное, мы добавили нативную интеграцию Uber. Больше не нужно переключать приложения. Можно запрашивать поездки, выбирать машины, смотреть, как автомобиль приближается — и всё внутри Transit. Не хотите видеть Uber? Запретите его в настройках. Вы — хозяин судьбы ваших поездок.
Какие ещё есть новости? Одна из наиболее запрашиваемых функций: раскрываемые стоп-списки в GO. Никаких больше «осталось 10 остановок… 9 остановок…».
Я заинтересовался этим описанием и нашёл его автора — Джо Макила, штатного копирайтера Transit. «Я думаю, что меня наняли в основном для написания пояснений к релизу», — сказал он мне. И это в его работе нравится ему больше всего.
Соласно Макнилу, в Transit считают, что пояснения к релизу — одна из лучших возможностей установления связи с пользователями. «В компании к пояснениям относятся так же серьёзно, как к записям в блоге», — говорит он. Разные черновые версии передаются между людьми. «Команда относится к ним очень требовательно, — говорит он. — Если у меня появляется плохая шутка, они её не пропускают».
Пояснения к релизу — способ разработчика сообщить пользователям о том, что изменилось в приложении, работающем на их телефоне. Они описывают новые возможности и держать пользователей в курсе по поводу важных изменений ПО. Обновление приложений — хорошая практика цифровой гигиены, поскольку новые версии исправляют проблемы и устраняют уязвимости.
Осенью ничто не сравнится с яблоками. Яблочные пироги [яблочный пирог — одно из характерных блюд кухни США / прим. перев.], яблочные пончики, и конечно же, Apple iOS. Посмотрите на эти свежие возможности, которые сделают ваше приложение Seamless лучше, чем когда-либо:
Более гибкая система предзаказа: можно менять заказ вплоть до 4 часов до момента доставки.
Удобные настройки заказа: переключайтесь между доставкой и самовывозом, а также между доставкой по возможности и предзаказом прямо на странице меню ресторана.
Обновление меню: выбирать блюда стало ещё проще благодаря переделанным пунктам меню.
Считаете, что приложение Seamless — клёвое? Ставьте оценку и пишите обзоры прямо сейчас!
Но писать пояснения к релизу бывает тяжело. Часто их составляет кто-нибудь уже тогда, когда команда разработчиков готова разместить новый код в магазине приложений — просто как послесловие. «У нас это когда-то было последним пунктом в списке, и на него никто не обращал внимания», — говорит Роб Гилл, бывший менеджер по пользовательскому восприятию в Perform Group, управлявшей разработкой десятков приложений.
В результате пояснения к релизу многих приложений скучны. Они повторяют несколько общих фраз, часто это варианты фразы «исправление багов» и «обновление быстродействия».
Но некоторые пояснения, и их авторы, демонстрируют индивидуальность. Макнил из Transit — один из них. Грег Гелднер, работающий над услугами для пользователей в Medium, ещё один. Несколько лет назад Гелднер заметил, насколько скучными стали пояснения к релизам. «Это просто исправления багов, все про исправления багов», — говорит он.
Он с коллегой Ником Фишером вызвались начать писать их для Medium, увидев «небольшую возможность пошутить друг с другом». Их работа состояла в том, что они делились идеями друг с другом до тех пор, пока один из них не засмеётся. В своих заметках Medium размещала конкурс на футболки, публиковала чат разработчиков в Slack, писала выдуманную историю про программиста Питера, которого наняли, а затем уволили за работу над приложением.
«Сначала мы не особенно задумывались над тем, чтобы передавать какую-то реальную информацию», — признаёт Гелднер. Для одного важного обновления, позволявшего пользователям логиниться через электронную почту и учётную запись в Facebook, они с Фишером написали пояснения, много раз использовав игру слов на основе песен Кенни Логгинса. Это было фиаско — никто не узнал, какие же улучшения были сделаны на самом деле.
Гилл из Perform Group недавно написал запись в блоге, призывающую разработчиков лучше писать примечания к релизам. Он советует авторам использовать списки с маркерами, разделять параграфы и указывать простое и понятное резюме главных изменений в самом начале. Одни из его любимых примечаний бывают у Evernote, 1Password и Tumblr.
Они страшненькие, ползучие и отвратительные. Да, мы сейчас о багах. Какие же хорошие новости? Мы устранили их кучу из этого выпуска приложения Yelp.
Когда примечание не достигает цели, как то, с Логгинсом, Гелднер говорит, что узнаёт об этом от пользователей Medium. «Обычно мгновенную обратную связь получаешь через Twitter и магазин приложений, — говорит он. — Люди пишут типа „Хватит уже этих дурацких примечаний, расскажите, что тут есть“.
Теперь Гелднер пытается немного прикрутить юмор и давать больше полезной информации, когда Medium планирует крупное обновление. Однажды он даже опубликовал немного изменённый код из самого обновления в пояснениях к релизу. Макнил использует похожий подход в Transit, немного придерживая своё творческое начало, когда приложение испытывает серьёзные изменения.
Но всем угодить невозможно. Статья из TechCrunch от 2015 года озаглавлена „Пояснения к релизам приложений тупеют“ открещиваются как от банальных обновлений, так и от попыток „перфоманса“, типа того, когда Medium добавила в примечание изображение бага в ASCII со словом „FIXES“ (исправления).
Некоторые критики этого необычно жанра любят заявлять, что эти пояснения всё равно никто не читает, особенно когда пользователи могут разрешить автоматические обновления приложений. Но одно из пояснений Макнила попало на первую страницу reddit. В Twitter пользователи Transit просят выложить его фотографии, рекомендуют поднять ему зарплату и умоляют „не переставать“ писать пояснения.
В Medium Гелднер часто обращается к популярной культуре в поисках вдохновения — оно может прийти из рождественской песенки, политических дебатов, кино. Его творчество иногда пробуксовывает, поскольку он пишет пояснения уже почти три года. „Я уже многие из них забыл, — говорит он. — Это тоже часто случается. Я предлагаю: “Давайте сделаем Парк юрского периода», а кто-то отвечает: «Так мы уже это делали».
Зачем писать пояснения к релизам, если можно поиграть в «виселицу»? ё
Для Гелднера и Макнила это задачи как профессионального, так и личного свойства. «Я бы сказал, что авторы, пишущие пояснения к релизам, друг друга не знают, — говорит Макнил. — Но между нами однозначно идёт состязание».
Пояснения Макнила вызвали перебранку в Twitter между Transit, Pocket Casts и Medium. Он также был приглашённой звездой в примечаниях к релизу других приложений, включая и Medium.
Для тех, кто хочет сделать себе имя на сочинении пояснений к релизам, у него есть совет. «Я бы сказал, будьте открытым к новым идеям, и, может, хлебните пивка перед написанием, — говорит он. — Тут правил нет».
Управлять релизом просто: правила и этапы release management
Релиз является одним из самых важных и ожидаемых событий в жизненном цикле продукта. Приготовления к релизу могут занимать много усилий и времени, участия всей команды и заинтересованных сторон. Хорошо, если выпуск продукта или его версии проходит гладко и становится настоящим праздником. Но бывает иначе. Что из себя представляет эффективный релиз-менеджмент и как менеджерам продукта научиться его секретам?
Релиз связан с запуском нового продукта/сервиса/услуги или набором новых функций, изменений, которые становятся доступны клиентам или пользователям и обеспечивают новую продуктовую ценность.
Часто релиз состоит из ряда решений по устранению проблем и улучшений предоставляемых услуг, может включать изменения в ПО. На самом деле, это довольно значимое событие как для внутренних команд, так и для целевой аудитории.
Управление релизами помогает командам планировать свою работу и видеть конечный результат, а для клиентов это, своего рода, гарантия качества и получения новой ценности.
Хорошо подготовленный релиз — это не только предоставление доступа к новым техническим возможностям продукта. Это конечная дата, когда ваша команда может предоставить новый пользовательский опыт, поддержать и развить взаимодействие с ним.
Релизы должны включать все дополнительные задачи и активности, такие, например, как обновления на официальном сайте и в социальных сетях, обучение команды поддержки, обновление всех маркетинговых материалов и т. д.
Основная цель управления релизом — создавать, тестировать и доставлять новые возможности, которые будут удовлетворять все продуктовые требования и намеченные цели.
Продуктовым командам стоит тщательно планировать релизы, поскольку они являются новым предложением, которое ожидают клиенты.
Что включает процесс управления релизом?
Понимание процесса управления выпуском продукта может отличаться у разработчиков и нетехнических специалистов. Важно учитывать все аспекты релиза и прислушиваться к мнению каждого члена команды.
Процесс управления релизом может включать следующие этапы:
В управлении релизом продукта могут участвовать практически все члены команды.
Product manager и Project Manager
Менеджеры продуктов и менеджеры проектов несут основную ответственность за релиз. Функционал product manager project и manager отличается, но миссия у них одна — выпустить продукт и представить его клиентам в идеальном виде.
Разбработчики
Команда разработки — это ключевые игроки в управлении релизом, поскольку они участвуют в большинстве процессов в жизненном цикле продукта. Они оценивают изначальные затраты и время, определяют основные требования, создают документацию и разрабатывают функциональность. Они принимают главные решения о том, что можно сделать и что не нужно, а также сколько времени это займет.
Маркетинг
Маркетологи всегда должны “держать руку на пульсе” и быть в курсе того, чем живут конкуренты. В управлении релизом им важно тесно отрудничать с sales-менеджерами для получения новых и удержания существующих клиентов.
Тестировщики
Тестировщики работают вместе с разработчиками. Их задача — тестировать результаты исследований и разработки, основываясь на установленных критериях. Продукт не придет к релизу, пока не будут учтены все замечания и критерии прохождения тестирований.
Служба поддержки
Support-команда или отдельный специалист поддержки первыми получают сообщения, елси что-то пошло не так. Они должны понимать и знать все о релизе и должны быть должным образом подготовлены на всех уровнях еще на стадии планирования.
Помимо этих основных ролей, к управлению релизом могут привлекаться и другие специалисты: отдела закупок, финансисты, sales, биллинг, system engineering и др.
Почему нужно внедрять процесса управления релизам?
Что такое Release Notes в процессе управления релизом?
Release Notes — это примечания к версии продукта, в которых описываются изменения между выпускаемой и предыдущей версиями этого продукта. Такой документ может составляться для пользователей и для внутренних команд: тестировщиков, маркетологов, службы поддержки.
Когда используются примечания к релизу?
Примечания к релизу распространяются вместе с продуктами. Иногда — когда продукты все еще находятся в разработке или тестировании. Документ может быть доставлен клиентам при выпуске обновления (для продуктов, которые уже были использованы клиентами).
Вы можете найти различные варианты написания Release Notes, поскольку для этого документа нет единого стандарта или формата. В разных компаниях менеджеры продуктов, тестировщики и разработчики, которые обычно ответственны за написание примечаний, обычно используют свои собственные шаблоны.
Вот как выглядит страница с примечаниями к релизу у Firefox:
Как писать примечания к релизу?
Содержание документа зависит от типа релиза. Вот пример основных пунктов:
Заключение
Управление релизом во многих компаниях становится отдельным самостоятельным процессом, который сообщает заказчику дату выпуска продукта и основные этапы его развития. Заказчик участвует в приоритизации и вовлечен в определение содержания релиза.
Процесс позволяет менеджерам продуктов и команде своевременно оценить загрузку и управлять объемом работ, доставлять изменения в срок. Управление релизами позволяет собирать собственную статистику, с которой удобнее в дальнейшем обосновывать запросы на дополнительные ресурсы.
Если вы хотите детальнее разобраться в теме release management и отыскать интересные инсайты разных компаний, следующие книги будут полезными: (на английском языке)
Как организовать релиз
Как готовиться к релизу?
Выбрать ответственного человека
Можно дежурить по очереди, либо бросать игральные кости, либо тянуть спички —любой способ хорош. Важна ротация людей и обучение тех, кто не умеет делать релиз. Например, при броске костей можно ввести правила что тот, кто дежурил в прошлый раз, имеет право перебросить, а если дежурил два раза подряд, то автоматически не дежуришь. Дежурство не должно восприниматься как наказание или повинность, и обязательно должны быть люди, которые могут подстраховать.
Настроить календарь
Настроить дату в корпоративном календаре и убедится что все стейкхолдеры в курсе.
Сделать таблицу в вики
Укажите таблице версию, дату и человека, ответственного за релиз. Это больше нужно для ведения исторических данных. Можно и нужно тут же отметить, был ли релиз успешный и что именно вошло в релиз.
Release notes
Это то самое “что именно вошло в релиз”. В первую очередь, этими данными нужно поделится с аналитиками: любые изменения в KPI они могут сравнивать с тем, что вошло в релиз. На основании этих данных они могут делать выводы, какой функционал нужен пользователям, какие идеи хорошие, а какие нет, и что войдет в следующею итерацию.
Внутренний анонс
Другим отделам важно знать когда произошел релиз, чтобы, например, сделать посты в соц. сетях о новой версии продукта (создать инфоповод), следить за KPI (возможен рост или падение метрик) и т.д.
Во время релиза
Создать релизный бранч
Код, который подлежит выпуску не должен меняться, за исключением исправления критических багов. И в идеальном случае любой фикс должен пройти пул-реквест. Так же все тесты должны быть зеленые.
Отправить уведомление
Нужно уведомить всех по почте или в мессенджере о том, что создан релизный бранч и идет подготовка к релизу.
Сделать тэг
Обязательно сделать тэг, когда релиз финализирован, и затянуть фиксы в девелоп-ветку.
Сделать сам релиз
В идеальном варианте у вас должны быть механизмы, которые контролируют релиз: например, сделать релиз только на 10% пользователей или только на не платящих. Это необходимо для того. чтобы уменьшить урон от ошибок, которые возникли в процессе разработки и не были найдены во время тестирования.
Релиз одной кнопкой
Мифический. Безусловно, чем меньше человеческого фактора участвует в релизе, тем лучше. Но это нормально, если не все получается автоматизировать.
Если все пошло не так, как планировалось
Конечно же в случае какой-либо ошибки нельзя друг друга обвинять, а нужно решить проблему вместе и придумать план по предотвращению подобных инцидентов в будущем.
После релиза
Мониторить
Не забывайте мониторить ошибки, нагрузку на сервера. Также стоит обратить внимание на KPI: если вы сделали релиз и у вас упало DAU, то, возможно, что-то работает не так хорошо, как должно было, либо сломаны сами средства мониторинга. Любую подозрительную активность стоит проверить.
Сообщить об успехах и неудачах
Намного лучше если о проблеме узнают от разработчиков, а не от пользователей. И конечно же, если вы решили какие-то проблемы, то этим можно смело похвалиться.
Провести ретроспективу
Это, конечно же, частично зависит от методологии разработки, но если что-то в процессе релиза пошло не так — это стоит обсудить. Если что-то было хорошо, то это также стоит обсудить. В идеале на доске на каждый пункт неудачи должен быть пункт успеха либо благодарность коллеге. Это поможет не скатить ретроспективу в нытье и негатив.
Заказать пиццу и отпраздновать
Во время таких посиделок просто коллеги становятся друзьями и боевыми товарищами. А это значит, что в следующем бою друзья не подведут.
Начать подготовку к следующему релизу
Мне очень нравится идея Release train, когда каждый релиз проходит регулярно в четко обозначенные даты. Благодаря этому механизм релиза отлаживается командой. Как я писал выше, не обязательно делать релиз на 100% пользователей: можно выкатить на небольшую группу людей.
Как мы автоматизировали процесс генерации Release Notes
Всем привет! Меня зовут Семен. Я Java-разработчик и руководитель группы Java-разработки в Центре Big Data компании MTS Digital. В этом посте я хочу поговорить о Release Notes. Что это такое, почему не стоит писать их вручную и какие есть способы автоматизации. Покажу и реальный пример того, как организована работа с Release Notes в нашем проекте.
А что это?
Release Notes — это документация, которая характеризует последний инкремент продукта. Новые фичи, баг фиксы и так далее. Она представляет ценность как для разработчиков, так и для менеджеров, которые хотят знать, как развивается проект. Если вы хотя бы раз проводили еженедельные демо, то понимаете, как сложно порой вспомнить все мелкие детали, которые были затронуты в текущем спринте. Как же составлять Release Notes? Самый очевидный способ — руками. Его и рассмотрим.
Делаем Release Notes вручную
Самый главный плюс — для этого не требуется никаких специальных знаний, а также изменения существующих CI/CD процессов. Нанимаем технического писателя и поручаем это все ему. Что может быть проще? Однако тут «есть пара моментов».
Технический писатель может быть не погружен глубоко в продукт. Соответственно, он не сможет самостоятельно определить, что конкретно изменилось в новой версии. Понадобится разработчик, который будет доносить эту информацию. Фактически здесь получается двойная работа. Разработчик объясняет техническому писателю, что добавилось и убавилось. А технический писатель в свою очередь рассказывает всем остальным.
Процесс по документированию новой версии будет очень трудоемким. Здесь оказывает влияние много факторов. Например, как вы описываете задачи в таск-трекинговых системах (полно и развернуто, или кратко и на скорую руку). Как вы оформляете пул-реквесты. Как в целом архитектурно построена ваша система, насколько сложно в ней ориентироваться.
Велика вероятность допустить ошибку. Забыть упомянуть об исправлении важного бага, или случайно написать про фичу, которая будет сделана только в следующем спринте. Чем больше изменений в релизе, тем больше вероятность промаха.
Как видим, формировать Release Notes с помощью человеческих усилий не рационально. Значит, нужно автоматизировать процесс, верно? Да, но и тут возникает ряд вопросов.
Как определять, что изменилось, а что — нет?
Если установить определенные правила контрибьютинга, по которым изменения можно будет отслеживать, как гарантировать их соблюдение?
Мы поддерживаем несколько версий одновременно. Как автоматизировать процесс единообразно?
Что есть «изменение»?
Инкремент продукта можно мерить маленькими и большими шагами. Маленький — это коммит в репозитории. Большой шаг — это задача в таск-трекере (Jira, Trello, Github/Gitlab Tickets и так далее). Первый я бы назвал technical oriented, тогда как второй — business oriented стратегией. Они не являются взаимоисключающими и их вполне можно использовать совместно, ведь у каждого способа есть свои плюсы и минусы.
Technical Oriented Release Notes
Давайте начнем с более простого варианта. Предположим, что мы используем классический git-flow: develop и master ветка. Из develop раскатываются nightly билды, а при каждом мерже в master деплоится новая версия на production. Иначе говоря, осуществляется релиз. Вот на эти релизы нам и нужны Release Notes.
Найти коммиты нового релиза не составляет труда.
На словах все звучит красиво. Но на деле есть много подводных камней.
Зачастую разработчики пренебрегают написанием информативных сообщений коммитов. Из-за этого вместо понятного списка изменений вы можете получить полотно из fix, update, add, delete и.т.д.
В Release Notes попадут также инфраструктурные сообщения от вашего вендора git-сервера (Merge branch x to y, Merge pull request from z).
Во многих командах есть практика squash’ить коммиты перед мержем пул-реквеста, из-за чего большая часть информации о релизе будет безвозвратно утеряна.
Однако проблемы на этом не заканчиваются. Дело в том, что коммиты, (к сожалению), не представляют большой ценности для бизнеса. Даже если каждое сообщение будет максимально продумано и грамотно написано, скорее всего, это не даст продакт-оунеру никакой ценной информации, ведь разрозненный список коммитов тяжело дифференцировать в отдельные юниты работы.
Business Oriented Release Notes
Вот если бы вы вставили названия и описания задач, которые сделали, это было бы другое дело. (с) Типичный продакт-оунер.
Ну что же, давайте попробуем.
Список новых коммитов — это единственное, что мы можем узнать при формировании релизов. Значит, нужно каким-то образом связать коммиты и задачи в доске между собой. Решение довольно очевидно: в каждом сообщении о коммите указываем id соответствующей задачи. После этого можно распарсить айдишники из отфильтрованных коммитов и с помощью API получить необходимую нам информацию.
Рисунок 1. Общая схема доставки Business Oriented Release Notes
Такой подход позволяет объединить изменения кода с конкретными задачами бизнеса. Более того, коммиты (хэши и сообщения) можно вставлять в письма как дополнительную техническую информацию.
Все в этом подходе хорошо, кроме одной детали. Откуда мы знаем, что разработчики будут писать сообщения в коммитах так, как мы этого хотим? Хороший вопрос. Конечно, можно установить правила, описать их в CONTRIBUTING.md и надеяться, что люди станут их выполнять.
Но хотелось бы автоматизировать эту проверку. Причем желательно, чтобы она носила превентивный характер. То есть не позволяла бы написать некорректное сообщение коммита. К счастью, такой инструмент есть.
Есть еще один момент. Откуда мы знаем, что задачи в таск-трекинговой системе тоже будут описаны грамотно? На самом деле, это проблема. Часто разработчики решают вопросы голосом, а потом описывают задачу двумя-тремя словами. К сожалению, нет универсального способа проверить название и описание задач на полноту и ясность. Единственное решение — это внедрение культуры. Объяснять и рассказывать, почему это важно. Например, если вы завели двусмысленную задачу в пятницу вечером, есть вероятность, что в понедельник утром вы уже не вспомните, что конкретно надо было сделать.
Git Hooks
Когда люди упоминают Git хуки, чаще всего на ум приходят webhooks: триггеры на пул-реквесты, комментарии, аппрувы и так далее. Однако Git нативно поддерживает локальные хуки, которые слушают события, происходящие в репозитории на вашей машине. Одно из таких событий — попытка создания коммита. И вот это уже интересно.
Git hook представляет собой обычный скрипт, который выполняется перед или после какой-то операции. В данном случае мы будем говорить о хуке commit-msg. Если код возврата хука отличен от нуля, дальнейшая операция отменяется.
Есть пара нюансов с хуками, которые нужно понимать.
Второй нюанс — хуки сложно написать совместимыми сразу с несколькими операционными системами. Например, если вы написали хук на bash и у вас на Linux все работает отлично, то у вашего коллеги на Windows или MacOS могут возникнуть проблемы. Поэтому для хуков используют высокоуровневые языки, но с ними мы должны быть уверены, что у всех разработчиков будет установлен язык, на котором написан хук (да еще и нужной версии). Лишние зависимости — лишние проблемы.
К счастью, многие инструменты сборки проектов предоставляют плагины/библиотеки для кросс-платформенной реализации git hooks. Моим личным фаворитом является npm пакет Husky. С помощью пары конфигурационных файлов можно добавить необходимый нам хук.
Далее просто указываем команду обновления хуков в package.json “preinstall”. Теперь перед каждой установкой зависимостей проекта вместе с тем будут обновляться и хуки. Также хорошим автономным решением является пакет pre-commit.
Semantic Release
Если мы хотим автоматизировать процесс доставки Release Notes, встает проблема версионирования ПО. Можно создать свой набор правил. Например, поднимать нужную цифру в номере версии в зависимости от названия ветки, анализировать коммиты, задачи, теги и так далее. Или можно взглянуть на существующие готовые решения, которые подойдут для вашего проекта.
Библиотека следует нескольким концепциям.
Есть одна главная ветка в репозитории (master). Все остальные — короткоживущие
Новый Pull Request — новый релиз
Начальная версия продукта — 1.0.0
По умолчанию Semantic Release следует правилам коммитирования по гайдлайну Angular Commit Messages. Однако их можно переопределять, что поможет в решении проблемы с культурой написания commit-message, которую я описывал выше.
После успешного релиза (команда определяется конфигом) в Git создается новый тег, в описании которого добавляется отформатированная информация из полученных коммитов.
Вот пример конечного Release Notes из репозитория eslint-plugin-unicorn.
Рисунок 2. Пример конечных Release Notes, сгенерированных с помощью Semantic Release
Также отмечу, что библиотека не привязана строго к среде Javascript/Typescript. Благодаря наличию гибкой конфигурации ее можно интегрировать с любой системой сборки проектов, которую вы предпочитаете. Помимо этого, есть уже готовые решения. Например, плагин для Maven и Gradle.
Как вы заметили, Semantic Release исповедует подход Technical Oriented Release Notes. На мой взгляд, он отлично подходит для разработки библиотек и фреймворков (особенно open-source), но является спорным решением для сервисов.
Во-первых, Semantic Release не подходит для поддержки нескольких версий одновременно. Строго говоря, эта фича поддерживается, но на мой взгляд сложность конфигурации и дополнительные специфические правила коммитирования не оправдают итоговый результат.
Во-вторых, релизы как правило привязываются к milestone или story, которые определяются потребностью бизнеса, а не признаком того, в каком формате вы написали сообщение коммита. Ну и в-третьих, релиз/деплой при каждом мерже в определенных ситуациях мера избыточная.
Как мы автоматизировали Release Notes
Вот мы и плавно подобрались к теме того, как автоматизация реализована у нас. Стек следующий: Gitlab, Jenkins, Jira и SonarQube. Схематично процесс формирования отображен на рисунке 3.
Рисунок 3. Процесс автоматической генерации Release Notes после деплоя
Разработчик пушит свои изменения в feature-branch (docs, refactoring, bugfix, и.т.д.) и создает Merge Request. Если все проверки (в том числе code-review) прошли успешно, изменения отправляются в develop ветку. Раз в день develop ветка разворачивается на dev-стенд (nightly builds).
После деплоя происходит процесс парсинга коммитов с целью определить ID задач, которые были затронуты в текущем релизе.
В данном примере будет получен список из задач MTS-2312 и MTS-2326.
Теперь по JIRA REST API запрашиваем основную информацию по каждой задаче (название и описание).
Обратите внимание на параметр expand=renderedFields. Дело в том, что summary и description возвращаются в формате JIRA разметки. При добавлении таких строк в письма их становится тяжело читать и воспринимать. Ранее описанный параметр добавляет в ответ эти же поля в виде HTML, который гораздо проще сверстать в письме.
После проставляем на задачи лейблы конечных стендов, где были развернуты изменения. Например, dev, staging или prod.
В конце информация о выполненных задачах рассылается всем заинтересованным людям. Процесс для master ветки выполняется аналогичным образом.
К плюсам такого подхода можно отнести то, что он легко расширяем. Например, если мы поддерживаем несколько версий в production, то можно без проблем выполнять вышеописанный процесс для каждой релизной ветки.
В итоге мы получили автоматизированный процесс по рассылке писем со всеми задачи, которые были выполнены в рамках текущего релиза, а также их описаниями. Более того, он не требует значительных изменений в процессе разработки. Разработчикам достаточно лишь указывать ID задачи в Jira в каждом коммите. Но для того чтобы реализовать это на практике, требуется внедрение соответствующей культуры. Нужно объяснять сотрудникам, почему это важно и насколько позволяет повысить качество конечного продукта, ведь Release Notes — это тоже часть итогового результата.
Пожалуй, это все, что я вам хотел рассказать про автоматизацию Release Notes. Делитесь своими историями в комментариях. Расскажите, как этот процесс реализован у вас в проекте и спасибо за чтение!