应该如何编写发行说明？

发行说明应该如何编写有什么样的指导原则或最佳实践？ 我想我正在试图find适当的平衡点，而不是太具体。 另外，开发人员是否通常会为QA团队提供更多的发布说明，与提交给公众视图的发布说明进行比较？

Answer 1

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

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

QA发行说明应至less包含以下内容：

• 发布，buildnumber
• 所有固定的错误，包括错误号
• 所有增加的function，包括devise文档的链接

考虑你的观众，并尝试去思考他们需要什么。

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

Answer 2

我会看看stream行的F / OSS项目的发行说明：

• 火狐
• GIMP
• Ubuntu的
• Android的
• TeamCity的
• 等等

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

Answer 3

如果你有一个项目pipe理/问题跟踪系统，你一定要用它来生成你的发行说明。 Trac和Redmine尤其擅长这一点。

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

• 记住你的听众。 如果这是一个iPhone应用程序，很less有人会关心Foo类中第572行的特定逻辑错误是否被修复。 但他们会关心很多“应用程序现在对加速度敏感”。
• 尽可能广泛地总结新的发展，function和错误修正。 如果你可以把这些主题联系起来（例如“我们实现了generics和匿名types”），那么简短的介绍就是给人们一个大局的好方法。
• 详细说明已修复的具体事情，并提供指向您的公共bug跟踪器的链接（如果有的话）。 这通常可以自动生成。
• 不要提供令人难以忍受的细节。 对每个添加或修正的事物的单行或双行总结应该足够了。
• 始终包含特定的版本标识符（例如“v.1.4.5”）。

Answer 4

这真的取决于观众。 对于技术用户（例如使用您的API的开发人员），您可以是非常技术性的。 另一方面，您创build的应用程序的高级最终用户可能只对新function和主要更改感兴趣。

在这两者之间也是非技术性用户，例如支持部门。 对于这些人，可以在没有低级技术细节的情况下给出详细描述，例如“修正了logging未保存在数据库中的错误”。

Answer 5

在我看来，发行说明中的​​一个最佳做法是自动化。 如果修订控制系统提交消息有某些最佳实践（ http://drupal.org/node/52287 ），则可以通过自动脚本创build发行说明（ http://cvs.drupal.org/viewvc.py/ drupal / contributions / tricks / cvs-release-notes / ）。 这将创build真正好的发行说明： http : //drupal.org/node/226165

Answer 6

发行说明的主要贡献者将是您的开发团队。 允许开发人员和testing人员针对与TFS中的变更集关联的工作项目捕获任何发行说明相关信息是一个好习惯。

然后你可以使用像http://tfschangelog.codeplex.com这样的开源项目来生成发行说明。; 它有GUI版本和一个命令行版本，可以很容易地在夜间安排你的版本注释报告。