如何写出发行说明？

Question

是否有关于如何编写发行说明的指南或最佳实践？我想我正在努力找到适当的平衡点，而不是太具体。另外，开发人员通常会为QA团队提供更多的发布说明，而不是提交给公众查看的发布说明吗？

Answer 1

公开发行说明至少应包含：

• 发布，buildnumber
• 所有固定的公共错误
• 所有添加的公共功能

质量检查发布说明至少应包含：

• 发布，buildnumber
• 所有修复的错误，包括错误编号
• 所有添加的功能，包括指向设计文档的链接

考虑您的受众并尝试思考他们需要什么。

要添加的另一件事是对某些平台的新支持或停止支持。 （例如，我们放弃了对Win3.1的支持并添加了Vista 64位）。

Answer 2

我会看一下流行的F / OSS项目的发行说明：

• Firefox
• GIMP
• Ubuntu
• Android
• TeamCity
• 等

所有这些项目都有相当可读和平衡的发行说明。

Answer 3

如果您有项目管理/问题跟踪系统，您肯定应该使用它来生成发布说明。 Trac和Redmine特别擅长这一点。

发布点应该有一些属性，IMO：

• 请记住您的观众。如果这是一款iPhone应用，很少有人会关心Foo类中第572行的特定逻辑错误已修复的事实。但他们会非常关心“应用程序现在对加速计敏感”。
• 如果可能的话，以广泛，彻底的方式总结新的发展，功能和错误修正。如果你可以将这些主题绑定在一起（例如“我们实现了泛型和匿名类型”），那么简单介绍一下就可以让人们了解大局。
• 列出已修复的特定内容，并附带指向您的公共错误跟踪器的链接（如果有）。这通常可以自动生成。
• 不要提供令人难以忍受的细节。添加或修复每件事物的单行或双行摘要应该足够了。
• 始终包含特定的版本标识符（例如“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中的变更集链接的workItem捕获任何与发布说明相关的信息是一种很好的做法。

然后，您可以使用http://tfschangelog.codeplex.com之类的开源项目来生成发行说明。它具有GUI版本和命令行版本，可以方便地每晚安排发布说明报告。

Answer 7

我发现ReleaseNotesHub很好用。它为生成和发布发行说明提供了最佳实践。