Как следует писать заметки о выпуске?

Question

Существуют ли какие-либо рекомендации или рекомендации по написанию примечаний к выпуску? Я думаю, что я пытаюсь найти правильный баланс между высказыванием мнения, не будучи слишком конкретным. Кроме того, обычно ли разработчик предоставляет гораздо больше примечаний к выпуску для команды QA по сравнению с тем, который представлен для публичного просмотра?

Answer 1

Публичные заметки о выпуске должны содержать как минимум:

• выпуск, номер сборки
• все исправленные публичные ошибки
• все добавленные общедоступные функции

Примечания к выпуску QA должны содержать как минимум:

• выпуск, номер сборки
• все исправленные ошибки, включая номер ошибки
• все добавленные функции, включая ссылки на дизайнерские документы

Рассмотрите свою аудиторию и попытайтесь подумать, что им нужно.

Еще одна вещь, которую нужно добавить, - новая или прекращенная поддержка определенных платформ. (Например, мы прекратили поддержку Win3.1 и добавили 64-битную Vista).

Answer 2

Я бы посмотрел заметки о выпуске популярных проектов F / OSS:

• Firefox
• GIMP
• Ubuntu
• Android
• TeamCity
• и т.д.

Все эти проекты имеют довольно читаемые и сбалансированные заметки о выпуске.

Answer 3

Если у вас есть система управления проектами / отслеживания проблем, вам определенно следует использовать ее для создания заметок о выпуске. Trac и Redmine особенно хороши в этом.

Точки выпуска должны иметь несколько свойств, IMO:

• Запомните свою аудиторию. Если это приложение для iPhone, немногие будут беспокоиться о том, что исправлена ​​конкретная логическая ошибка в строке 572 в классе Foo. Но они будут беспокоиться о том, что «приложение теперь чувствительно к акселерометру».
• Кратко изложите новые разработки, функции и исправления ошибок, если это возможно. Если вы можете тематически связать их (например, «мы внедрили дженерики и анонимные типы»), короткая реклама об этом - хороший способ дать людям общую картину.
• Перечислите конкретные вещи, которые были исправлены, со ссылками на ваш общедоступный баг-трекер, если таковые имеются. Обычно это может быть сгенерировано автоматически.
• Не предоставляйте мучительных деталей. Одноступенчатых или двухстрочных сводок по каждой вещи, которая была добавлена ​​или исправлена, должно быть достаточно.
• Всегда включайте конкретные идентификаторы релиза (например, "v.1.4.5"), в зависимости от ситуации.

Answer 4

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

Между ними нетехнические пользователи, которым тоже нужны подробности, например, отдел поддержки. Для этих людей вы можете дать подробное описание без технических подробностей низкого уровня, например «Исправлена ​​ошибка, когда запись не сохранялась в базе данных».

Answer 5

На мой взгляд, лучшая практика с заметками о выпуске - автоматизация. Если существуют определенные рекомендации для отправки сообщений системой контроля версий (http://drupal.org/node/52287),, вы можете создавать заметки о выпуске с помощью автоматизированного сценария (http://cvs.drupal.org/viewvc.py/drupal/contributions/tricks/cvs-release-notes/).). Это создаст действительно хорошие заметки о выпуске: http://drupal.org/node/226165

Answer 6

Главным участником заметок о выпуске будет ваша команда разработчиков. Это хорошая практика, позволяющая вашим разработчикам и тестировщикам собирать любую информацию, связанную с примечаниями к выпуску, относительно ваших рабочих элементов, связанных с наборами изменений в TFS.

Затем вы можете использовать проект с открытым исходным кодом, например http://tfschangelog.codeplex.com, для создания заметок о выпуске. Он имеет версию с графическим интерфейсом и версию командной строки, что позволяет легко планировать отчеты о выпуске заметок на ночной основе.