Начните с шаблона, ориентированного на пользователя
Замените каждое поле в скобках проверенной информацией. Удаляйте неприменимые разделы вместо выдумывания функций. Если при обновлении не нужны дополнительные действия, явно укажите это после проверки поддерживаемого пути обновления.
# [Версия] — [Дата выпуска]
## Главное
- [Заметное пользователям улучшение и кому оно полезно]
## Обновление
- С версии: [поддерживаемая предыдущая версия]
- Действие: [необходимая миграция или отсутствие необходимых действий]
- Проверка: [как подтвердить успешное обновление]
## Изменения, нарушающие совместимость
- [Изменённое поведение, затронутые пользователи и ссылка на миграцию]
## Исправления
- [Решённая проблема и ссылка на обсуждение или запрос на слияние]
## Известные проблемы
- [Оставшееся ограничение и обходной путь]
## Участники
[Поблагодарите участников и добавьте ссылку на полный журнал изменений]Превратите сгенерированные примечания в понятное объяснение
GitHub умеет генерировать примечания со слитыми запросами, участниками и ссылкой на полный журнал изменений. Считайте этот результат черновиком. Проверьте границы выпуска, удалите неуместные записи и сгруппируйте изменения по задачам пользователей.
Например, фраза «Исправлен крайний случай парсера» мало что объясняет. Если это соответствует действительности, напишите, что CSV-файлы с пустым последним столбцом теперь импортируются правильно, и дайте ссылку на исправление с техническими подробностями. Не утверждайте, что решены все проблемы разбора, если изменён лишь один случай.
Проверьте путь обновления перед объявлением
Попробуйте описанное в документации обновление с поддерживаемой предыдущей версии. Проверьте ссылки для скачивания и соответствие документации выпуску. Отличайте предварительную версию от стабильной и сделайте оставшиеся ограничения легко доступными.
Опубликуйте информацию о выпуске, прежде чем ссылаться на неё в сообщении сообществу. В объявлении выделите одно существенное улучшение, а примечания к выпуску оставьте подробным справочным материалом. Собирайте последующие вопросы и при необходимости уточняйте инструкции.
Частые вопросы
Примечания к выпуску и журнал изменений — одно и то же?
Они частично совпадают. Журнал изменений фиксирует изменения во времени; примечания объясняют конкретный выпуск и его влияние на пользователей. Свяжите их ссылками, чтобы читатели могли переходить от обзора к подробностям.
Можно ли публиковать автоматически сгенерированные примечания без изменений?
Сначала проверьте их. В сгенерированных заголовках запросов могут отсутствовать шаги миграции, влияние на пользователей и известные проблемы.
Нужно ли включать каждое небольшое изменение кода в главное?
Нет. Выделяйте изменения, важные пользователям, а подробную техническую историю сохраняйте в журнале изменений, на который ведёт ссылка.