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

Ответ 1

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

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

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

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

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

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

Ответ 2

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

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

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

Ответ 3

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

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

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

Ответ 4

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

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

Ответ 5

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

Ответ 6

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

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