发行说明应该怎么写？答案

【问题标题】：How should release notes be written?发行说明应该怎么写？
【发布时间】：2010-10-12 21:52:45
【问题描述】：

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

【问题讨论】：

【解决方案1】：

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

QA 发行说明至少应包含：

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

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

【讨论】：

【解决方案2】：

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

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

【讨论】：

【解决方案3】：

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

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

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

【讨论】：

【解决方案4】：

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

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

【讨论】：

【解决方案5】：

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

【讨论】：

【解决方案6】：

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

【讨论】：

对此不确定。如果我搜索“ubuntu”，结果为零。
:) 你在哪里搜索“ubuntu”，你希望看到什么？
:) 也许我误解了“ReleaseNotesHub”，网站疯了。不要搜索 ubuntu。
他实际上是指release-notes.com（也是发行说明中心）。上面的网站太疯狂了。
Hi @StackTheUser releasenoteshub.com 完全自动生成来自 Azure Devops、GitHub 等许多来源的发行说明。我不知道您为什么还要费心使用其他任何东西。

【解决方案7】：

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

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

【讨论】：