Как Вы формируете release notes?

Question

[Валерий Абакумов]

Добрый день, уважаемые специалисты!

Поделитесь, пожалуйста, как Вы формируете release notes к разрабатываемым программным продуктам? Делаете ли Вы это автоматически или вручную? Какие средства используете?

Текущее окружение: есть JIRA, проект в Git-репозитории на TFS 2013 и, скорее всего, скоро будет Jenkins.

Answer 1

[Anton Bormotov]

При использовании тэгов, создании и именовании pull requests, разработчики следуют определенному "шаблону".
Например:
Feature 341: Add new css style
А потом, получить сообщения со всех merge коммитов, перед релизом, между последним тэгом и текущем HEAD (это maser ветка):
git log --merges --pretty=format:%b v1.0.7..HEAD
Это также можно добавить в Jenkins или Teamcity, как у нас.

Comments

[Валерий Абакумов]

qqwrst, добрый день! Если я Вас правильно понял, то у Вас все разработчики просто делают commit'ы в определенном формате, потом Вы эти коммиты вытаскиваете и, образно говоря, "кладете" куда-нибудь (в файл, например)?

[Anton Bormotov]

Добрый. Нет, немного не так.
У нас есть develop бранч.
Разработчик создает свой бранч (checkout из develop), например feature/update-qa.env-file
Фиксирует туда коммиты, а потом создает pull request (push на github обязательно, конечно).
Называя pull request, он следует определенному формату, но это не обязатено. Мы делаем это что бы иметь ту же систему именования, что и в task tracking tool.
Название pull request и есть в git log опция format:%b (см. man git-log, секция format:)

Таким образом нет необходимости использовать какой то "определенный формат" и потом делать grep.

Попробуйте так сделать, на тестовом репозитории, например.
Если что то непонятно, пишите, помогу по возможности.

[Anton Bormotov]

%b как я понял, это сообщение merge коммита, поэтому merge обязательно с опцией --no-ff.

[Валерий Абакумов]

qqwrst как Вы используете tag в git? какую информацию Вы пишете в tag?

[Anton Bormotov]

Очень просто - только номер новой версии (цифра меняется в зависимости от изменений):
1. Сливаем ветку develop в ветку master.
git clone -b master
git fetch origin develop
git merge --no-ff --no-edit origin/develop

2. Смотрим текущий список тэгов:
git tag -l
Вывод:
v1.1.1
v1.1.2
и т. д.

4. Извлекаем release notes между последним тэгом и текущим HEAD (как написал выше, с помощью git log)

3. Создаем новый тэг:
Либо git tag v1.1.3 and git push --tags origin master, либо curl запрос в github api, он там сам его создает и push не нужен.

[Валерий Абакумов]

Anton Bormotov у меня много вопросов :) вот смотрите: последний тег пусть будет v1.1.3. А что тогда будет в текущем HEAD? это HEAD ветки master? немного непонятно, что выведет git log между последний тегом и текущим HEAD... И еще вопрос: я правильно понимаю, что tag Вы указываете только при push после merge Вашей ветки develop с веткой master? а при простом commit Вы, получается, тег не указываете?

[Anton Bormotov]

Смотрите:
2 и 3 совершенно верно. Тэгируется только master ветка.
Когда в develop выполнили merge всех бранчей разработчиков, тестируем develop бранч на QA сервере. После того как тестировщики и проект мэнеджеры дают зеленый свет, мы делаем merge develop бранча в master. После этого тэгируем мастер новой версией. Соответственно, в мастере появляются все новые коммиты, в том числе merge коммиты от бранчей разработчиков. Сообщения этих merge коммитов и являются release notes для нас, поскольку несут описание новых фич/features.

А теперь первый ворос:
- Последний тег пусть будет v1.1.3. А что тогда будет в текущем HEAD?

Пусть v1.1.3 указывает на текущий HEAD мастера и мы сейчас в мастере. Предположим в develop бранче есть 5 коммитов. Мы сливаем изменения в мастер (git merge --no-ff origin/develop) и получаем 5+1 новых коммитов в мастере.
Теперь HEAD указывает на последний коммит.
Соответственно можно получить git log между v1.1.3 и HEAD.
Или создать новый тэг для текущего HEAD: git tag v1.1.4.
После этого посмотреть git log можно уже между двумя тэгами: v1.1.3 и v1.1.4

Надеюсь что то прояснит это небольшое объяснение. :)

[Валерий Абакумов]

Anton Bormotov здравствуйте. да, стало понятно, спасибо Вам большое!

Answer 2

[Saboteur]

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

Comments

[Валерий Абакумов]

Сергей спасибо! Какими плагинами на питоне Вы пользуетесь для "поста в ту же Жиру"?

[Saboteur]

Валерий Абакумов: А мы напрямую не пользуемся, у нас используется система ревью Gerrit, в которую идут коммиты, и Дженкинс тоже настроен с геррит-триггером.
Питоновский скрипт может послать что-то в Геррит или в Дженкинс через их АПИ, а при создании тикета в Jira указывается change в Геррите и они друг с другом общаются.

[Валерий Абакумов]

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

[Saboteur]

Через мессадж хук сразу при попытке сделать коммит, идет не пустое поле а шаблончик, ну например так:
#release notes

#what was changed (short)

#what was changed (long)

Все разработчики проинструктированы что именно и как заполнять в шаблоне, коммит с неправильно заполненными полями не пройдет ревью.
Зато потом из такого коммит мессаджа можно выкусывать любым скриптом, используя git log и др.