Мы делаем один из инструментов на этой странице. Мы постарались описать остальные по тому, для чего они созданы, а не по тому, где они не дотягивают, а раздел о нашем собственном продукте прямо говорит, кому не стоит его использовать.
Три категории
Размещённый виджет и страница
Вы пишете записи в их редакторе, они размещают страницу и дают вам виджет внутри приложения. Быстрее всего запустить, а записи живут на их инфраструктуре, а не на вашей. Beamer и AnnounceKit — самые явные примеры.
Пакет обратной связи с прикреплённым changelog
Changelog — это один модуль рядом с голосованием за функции, публичным roadmap и папкой обратной связи. Стоит того, если вы хотите весь цикл от одного поставщика, избыточно, если вы хотите только публиковать релиз-ноты. Canny, Frill и Featurebase находятся здесь.
Сгенерировано из вашего репозитория
Changelog производится из коммитов, pull request'ов или issue вместо ручного набора. Диапазон от файла, построенного в CI, до составленной, проверенной, опубликованной записи. git-cliff и github-changelog-generator находятся на файловом конце; LaunchNotes, Released и наш собственный продукт находятся на опубликованном конце.
Кратко
| Инструмент | Тип | Лучше всего для |
|---|---|---|
| Beamer | Размещённый виджет | Запустить панель «что нового» в приложении уже сегодня днём, без времени разработчиков. |
| AnnounceKit | Размещённый виджет | То же самое, но с большим вниманием к тому, кто какое объявление видит. |
| Canny | Пакет обратной связи | Команды, которым нужны голосование за функции и публичный roadmap, а changelog замыкает этот цикл. |
| Frill | Пакет обратной связи | Небольшие команды, которым нужна та же схема, что у Canny, но полегче. |
| LaunchNotes | Из репозитория | Крупные организации, которые координируют объявления между командами, часто с опорой на Jira. |
| Released | Из репозитория | Команды, которые живут в Jira и хотят получать changelog из issue, не выходя из неё. |
| git-cliff | Генератор файла | Open-source проекты, которым нужен CHANGELOG.md, собранный в CI из conventional commits, без какого-либо хостинга. |
| Changeloop | Из репозитория | Команды, которым нужна запись, составленная из объединённых pull request'ов и затем отрендеренная их собственным фронтендом из JSON-фида. |
Как выбрать
- Начните с того, где changelog должен появляться. Если он должен выглядеть частью вашего продукта, размещённая страница, на которую вы даёте ссылку, разочарует независимо от того, насколько хорош её редактор, и вам нужен либо виджет, который можно перестилизовать, либо фид, который вы рендерите. Если связанная страница подходит, размещённые инструменты требуют гораздо меньше работы.
- Затем спросите, кто пишет записи. Если ответ «инженер, объединивший изменение», выберите то, что читает ваш репозиторий, потому что всё остальное добавляет ручной шаг именно в тот момент, когда все заняты. Если ответ — маркетолог продукта, работающий по плану релиза, редактор подходит лучше, а автоматизация репозитория только помешает.
- Затем спросите, нужен ли вам остальной цикл. Голосование за функции и публичный roadmap действительно полезны и действительно являются большим обязательством. Покупка пакета ради его модуля changelog — это то, как команды в итоге платят за четыре вещи, чтобы использовать одну.
- Наконец, проверьте, что происходит с вашими записями, если вы уйдёте. Инструмент, который экспортирует их как структурированные данные, существенно отличается от того, где они живут на размещённой странице, которую вам пришлось бы парсить вручную.
Где подходит наш собственный инструмент, а где нет
Changeloop читает каждый объединённый pull request, составляет ориентированную на пользователя запись, отфильтровывает обновления зависимостей и рефакторинг, и удерживает черновик для проверки. Опубликованное отправляется в публичный JSON-фид с фидом roadmap рядом, плюс двухстрочный виджет и размещённая страница как резервные варианты. Фид — это суть: предполагаемая настройка в том, что вы рендерите свой changelog внутри собственного продукта своими компонентами.
Не выбирайте, если:
- Ваши релизы не берутся из ваших репозиториев. Он составляет черновики из объединений или, в режиме push, из push'ей, так что у команды, поставляющей изменения вне рабочего процесса на Git, нет ничего для проверки.
- Вы хотите голосование за функции и roadmap, за который голосуют ваши пользователи. Фид roadmap есть, но им управляют помеченные issue, а не голосование пользователей. Пакет обратной связи — правильная категория для этого.
- Вы хотите отточенный редактор и размещённую страницу в качестве основного продукта. Размещённая страница существует как резервный вариант, и инструменты, построенные вокруг своей, сделают это лучше.
- Вы одиночный open-source проект, которому нужен только CHANGELOG.md в репозитории. Используйте git-cliff, который бесплатен и создан именно для этого.
Частые вопросы
Нужен ли нам вообще инструмент?
Какое-то время нет. Файл markdown, или страница на вашем собственном сайте, — это вполне хороший changelog, и он ничего не стоит. Момент, когда инструмент начинает окупаться, — это когда написание записей становится шагом, который пропускают, или когда вы хотите одни и те же записи в трёх местах без поддержания трёх копий.
Можем ли мы позже переехать от одного из этих инструментов?
Полностью зависит от того, выходят ли записи обратно как структурированные данные. Спросите об этом до начала, а не после: это единственный вопрос в списке, ошибиться в котором дорого, потому что changelog — это растущий архив, и перепечатать два года его содержимого — не тот проект, который кто-либо одобрит.
А как насчёт написания их с помощью AI-ассистента?
Большинство из них теперь составляют записи с помощью какой-то модели. Это гораздо менее важно, чем то, что получает модель. Инструмент, который видит только тему коммита, может лишь переписать эту тему; тот, что видит заголовок и описание pull request'а, имеет достаточно, чтобы описать изменение с точки зрения того, что оно делает для пользователя. Спрашивайте, каков ввод, а не есть ли там AI.
Дополнительное чтение: автоматизация changelog и её пределы, о том, какой из четырёх шагов должен быть автоматическим.
Тот, что ставит фид на первое место
Составлен из ваших объединённых pull request'ов, удерживается для проверки, публикуется в JSON-фид, который вы рендерите сами. Бесплатно для одного репозитория, без карты.
Начать бесплатно