40

是否有任何关于如何编写发行说明的指南或最佳实践？我想我正试图在不太具体的情况下提出观点之间找到适当的平衡。此外，与提交给公众查看的版本相比，开发人员通常会为 QA 团队提供更多的发行说明吗？

4

7 回答 7

29

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

  • 发布，版本号
  • 所有已修复的公共错误
  • 所有添加的公共功能

QA 发行说明应至少包含：

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

考虑你的听众，试着想想他们需要什么。

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

于 2009-03-12T12:41:13.477 回答
23

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

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

于 2009-03-12T12:42:05.563 回答
11

如果您有一个项目管理/问题跟踪系统，那么您绝对应该使用它来生成您的发行说明。Trac和Redmine尤其擅长这一点。

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

  • 记住你的听众。如果这是一个 iPhone 应用程序，很少有人会关心 Foo 类中第 572 行的特定逻辑错误已得到修复这一事实。但他们会非常关心“应用程序现在对加速度计敏感”。
  • 如果可能，以广泛、全面的方式总结新的发展、特性和错误修正。如果您可以将它们按主题联系在一起（例如，“我们实现了泛型和匿名类型”），那么简短地介绍一下这是让人们了解全局的好方法。
  • 列出已修复的具体内容，并附上指向您的公共错误跟踪器的链接（如果有）。这通常可以自动生成。
  • 不要提供令人痛苦的细节。对添加或修复的每件事进行一或两行摘要就足够了。
  • 始终酌情包含特定的版本标识符（例如“v.1.4.5”）。
于 2009-03-12T12:41:42.057 回答
2

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

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

于 2009-03-12T12:42:13.100 回答
1

在我看来，发布说明的一个最佳实践是自动化。如果版本控制系统提交消息有某些最佳实践 ( http://drupal.org/node/52287 )，您可以通过自动化脚本 ( http://cvs.drupal.org/viewvc.py/ ) 创建发行说明drupal/contributions/tricks/cvs-release-notes/）。这将创建非常好的发行说明：http ://drupal.org/node/226165

于 2009-03-12T12:46:34.837 回答
1

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

于 2020-05-11T23:35:31.263 回答
0

发行说明的主要贡献者将是您的开发团队。允许您的开发人员和测试人员针对链接到 TFS 中的变更集的工作项捕获任何与发布说明相关的信息是一种很好的做法。

然后你可以使用像http://tfschangelog.codeplex.com这样的开源项目来生成发行说明。它有 GUI 版本和命令行版本，可以轻松地安排每晚的发行说明报告。

于 2012-06-05T12:33:43.810 回答