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

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

6 ответов

Решение

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Другие вопросы по тегам