Руководства для проектов

Шаблон примечаний к выпуску GitHub для открытых проектов

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

Редакция GitHubStart · Обновлено

Начните с шаблона, ориентированного на пользователя

Замените каждое поле в скобках проверенной информацией. Удаляйте неприменимые разделы вместо выдумывания функций. Если при обновлении не нужны дополнительные действия, явно укажите это после проверки поддерживаемого пути обновления.

# [Версия] — [Дата выпуска]

## Главное
- [Заметное пользователям улучшение и кому оно полезно]

## Обновление
- С версии: [поддерживаемая предыдущая версия]
- Действие: [необходимая миграция или отсутствие необходимых действий]
- Проверка: [как подтвердить успешное обновление]

## Изменения, нарушающие совместимость
- [Изменённое поведение, затронутые пользователи и ссылка на миграцию]

## Исправления
- [Решённая проблема и ссылка на обсуждение или запрос на слияние]

## Известные проблемы
- [Оставшееся ограничение и обходной путь]

## Участники
[Поблагодарите участников и добавьте ссылку на полный журнал изменений]

Превратите сгенерированные примечания в понятное объяснение

GitHub умеет генерировать примечания со слитыми запросами, участниками и ссылкой на полный журнал изменений. Считайте этот результат черновиком. Проверьте границы выпуска, удалите неуместные записи и сгруппируйте изменения по задачам пользователей.

Например, фраза «Исправлен крайний случай парсера» мало что объясняет. Если это соответствует действительности, напишите, что CSV-файлы с пустым последним столбцом теперь импортируются правильно, и дайте ссылку на исправление с техническими подробностями. Не утверждайте, что решены все проблемы разбора, если изменён лишь один случай.

Проверьте путь обновления перед объявлением

Попробуйте описанное в документации обновление с поддерживаемой предыдущей версии. Проверьте ссылки для скачивания и соответствие документации выпуску. Отличайте предварительную версию от стабильной и сделайте оставшиеся ограничения легко доступными.

Опубликуйте информацию о выпуске, прежде чем ссылаться на неё в сообщении сообществу. В объявлении выделите одно существенное улучшение, а примечания к выпуску оставьте подробным справочным материалом. Собирайте последующие вопросы и при необходимости уточняйте инструкции.

Частые вопросы

Примечания к выпуску и журнал изменений — одно и то же?

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

Можно ли публиковать автоматически сгенерированные примечания без изменений?

Сначала проверьте их. В сгенерированных заголовках запросов могут отсутствовать шаги миграции, влияние на пользователей и известные проблемы.

Нужно ли включать каждое небольшое изменение кода в главное?

Нет. Выделяйте изменения, важные пользователям, а подробную техническую историю сохраняйте в журнале изменений, на который ведёт ссылка.

Источники