Как следует писать заметки о выпуске?
Существуют ли какие-либо рекомендации или рекомендации по написанию заметок о выпуске? Я думаю, что я пытаюсь найти правильный баланс между высказыванием мнения, не будучи слишком конкретным. Кроме того, обычно разработчик предоставляет гораздо больше замечаний к выпуску для команды QA по сравнению с тем, что представлено для публичного просмотра?
6 ответов
Публичные заметки о выпуске должны содержать как минимум:
- выпуск, номер сборки
- все исправленные публичные ошибки
- все добавленные публичные функции
Примечания к выпуску QA должны содержать как минимум:
- выпуск, номер сборки
- все исправленные ошибки, включая номер ошибки
- все добавленные функции, включая ссылки на дизайн документов
Посмотрите на свою аудиторию и постарайтесь думать, что им нужно.
Еще одна вещь, которую нужно добавить, - новая или прекращенная поддержка определенных платформ. (Например, мы прекратили поддержку Win3.1 и добавили 64-битную Vista).
Если у вас есть система управления проектами / отслеживания проблем, вам определенно следует использовать ее для создания заметок о выпуске. В частности, 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/ для создания заметок о выпуске. Он имеет версию с графическим интерфейсом и версию командной строки, что позволяет легко планировать отчеты о выпуске заметок на ночной основе.