5.0 KiB
如何写出绝佳的发行说明
图像来源： opensource.com
恭喜！你已经准备发布你的软件包的最新版本了。现在，你需要保证你的发行说明整洁有序。当然，你可以写上“bug 修复以及性能改进”然后就算完成，但这并不能给你的用户传达任何信息。
发行说明同时用于支持和营销。它可以告诉你的的用户为什么这个发布版本对他们很重要，并可以向潜在用户展示你的软件。所以，你会希望它的内容简洁、易懂，最重要的是：确切。写发行说明的方式不止一种，所以本文只是一般提议，并不是一个命令。
人们在发行说明中写上一大段饱含愚蠢的叙事内容。如果你想这么写，那请自便——不过要记住，笑话通常是上下文相关的，你觉得很滑稽的内容，可能在你的读者眼里会变得索然无味。而且，你不能忘了写那些重要信息。
入门
你能从本文里学到的最简单的经验，可能是这一条：你的发行说明要写给读它的人看。对于面向用户的软件，发行说明中要注重面向用户的行为，而不是软件的内部实现。举个例子：写“点击‘取消’按钮会把你的电脑点着”，而不要写“在 cancelThatThing 函数中，thermalEventTrigger 的默认值被设为 True”。
尝试将每一条说明限制在一到两句话。发行说明的重点在于突出强调重要部分，而不是给出详尽的解释。如果你有一个公开的问题追踪页面，你可以在说明中包含问题链接（或者问题编号），这样关注此问题的读者可以通过链接来查看问题的详细内容。
你并不需要严格按照这种方法来写发行说明，但我比较喜欢下面的格式。开头写上版本号，以及发布日期。对于主要版本，你可能要再写几句话，来突出本次发布的主题。比如，“本次发布的重点在于添加了邮件客户端，因为这是所有软件的最终结束状态。”
兼容性更改
如果新版本中包含兼容性更改或默认行为，你最好将它们着重写出。你的用户、以及提供用户支持的人会感谢你的。在发行说明中描述出现更改的地方，如何实施更改，以及用户不执行更改会导致的后果。对于某些次要版本，你可能没有做出任何会导致不兼容的更改，那你可以省略此部分。
功能及改进
" 现在，你该炫耀你的软件包含的那些酷的、新奇的东西了，但是要记得站在用户的角度来写。比如，“该软件现在支持自动检测午餐照片，并将其发布到 Instagram 上。”
已解决的问题
没有软件是完美的，所以在这部分中你需要告诉读者们你的团队为了使这个项目更好一点而做的所有努力工作。因为那些不好的行为已经被解决了，所以应该用过去式来写这一部分。如果某个 bug 的定位很明确，那应该在这部分中写上相关信息。其它的一些项目可能也会包含这一节中所述的 bug.
已知问题
因为没有软件是完美的，所以永远会存在未解决的 bug. 在这一节中，你需要列出这些已知的问题。你不需要解决所有的问题；专注于影响功能的错误，如果这些是在上个版本发布后发现的，你可能需要优先解决。这一部分的文字用将来时完成。当你把这些问题解决，你只需要改变动词的时态，然后把它们移到上个部分即可。
作者简介：
Ben Cotten - Ben Cotten 是一个受过专业训练的气象学家，但他现在是一位高性能计算工程师。Ben 是一位循环计算领域的布道者。它是一个 Fedora 用户及贡献者，与他人一同创办了一个本地开源会议组，是开源计划的成员，还是软件自由保护的支持者。你可以在 Twitter 上找到他（@FunnelFiasco）。
译者简介：
StdioA —— Pythoner, Player.
via: https://opensource.com/article/17/3/how-to-improve-release-notes
作者：Ben Cotton 译者：StdioA 校对：校对者ID