85 lines
3.3 KiB
ReStructuredText
85 lines
3.3 KiB
ReStructuredText
Release Notes写作注意事项
|
||
--------------------------------
|
||
|
||
* overview文件夹下的overview.rst用来写模块概述，简单描述该模块的定义、作用等内容。
|
||
* 如果写新增版本的releasenotes，请先按版本号新建文件夹，比如新增了0.1.1版本，则新建文件夹并命名为 ``0.1.1``，在 ``0.1.1`` 文件夹下新建文件index.rst，建议将之前版本的index.rst copy过来直接修改。
|
||
* 将新增文件添加到工程根目录下的 ``index.rst`` 主索引文件中，否则新增内容将无法包含在最终文档中。
|
||
* 按照rst语法、release notes写作规范，写变更内容。
|
||
* release notes写代码的修改、变更等相关内容，和文档的更新历史没直接关系。文档的“更新历史”只写与文档相关的变更。
|
||
* 执行 ``./makelatexpdf.sh`` 编译文档。
|
||
|
||
Release Notes写作规范
|
||
------------------------
|
||
|
||
**特性变更：**
|
||
|
||
如何写：
|
||
|
||
* 该章节包含新增特性、删除特性以及修改特性。新增算子、新增接口、删除算子、删除接口以及算子和接口的修改变动，都在该章节详细描述。
|
||
* 用无序列表的方式详细描述每一项内容。
|
||
* 修改部分要详细描述修改原因，修改能带来什么样的好处。 删除部分也要说明删除原因。：
|
||
|
||
举例如下：
|
||
|
||
- 新增xxx特性，支持xxx视频的播放。
|
||
- 删除xxx特性，因为xxx特性为临时方案，目前已被YYY特性取代，因此删除xxx临时特性。
|
||
- 新增x1、x2算子以支持xxx功能。
|
||
|
||
**已修复问题：**
|
||
|
||
如何写：
|
||
|
||
第一个版本的Release notes该章节无需写作。后续版本，已解决的遗留问题要在该章节描述。
|
||
|
||
已修复问题至少要描述清楚两点：
|
||
|
||
1.解决了什么问题；
|
||
2.因为解决该问题做了什么样的修改。
|
||
|
||
可以按以下句式：
|
||
|
||
* 通过修改xxx，修复了xxx问题
|
||
|
||
**已知遗留问题：**
|
||
|
||
如何写：
|
||
|
||
* 该章节描述在该版本还存在的问题，或者已给用户承诺的暂时未达标的规格要求。
|
||
* 如果有多个遗留问题，每个遗留问题用无序列表的方式描述，祥见下面的举例。
|
||
* 该部分内容必须包含“现象：”、“原因：”、“影响：”、“规避措施：”四个部分，可参见下面的举例。
|
||
|
||
举例如下：
|
||
|
||
* 080p分辨率以上的视频问题件无法播放。
|
||
|
||
**现象：**
|
||
|
||
详细描述出现该问题后的现象。该现象是用户可以直接看到的，不是问题本身的描述。比如：
|
||
|
||
当播放1080p以上分辨率的视频文件时，会出现卡段或掉帧的现象，导致视频播放失败。
|
||
|
||
**原因：**
|
||
|
||
描述出现该问题的原因，或者用户如何操作才会导致该问题，比如：
|
||
|
||
当前采用的VPU不支持1080p视频文件的播放。
|
||
|
||
**影响：**
|
||
|
||
详细说明该问题对用户可能造成的影响,比如：
|
||
|
||
该问题会导致无法播放1080p分辨率以上的视频文件。
|
||
|
||
**规避措施：**
|
||
|
||
对该问题有无规避措施。如果无规避措，直接写“无规避措施”，如果有规避措施，详细描述该问题的规避措施.比如：
|
||
|
||
无。
|
||
|
||
**注意：**
|
||
|
||
在上一版本记录的已知遗留问题，如果在当前版本依然存在，在当前版本需要继续记录。
|
||
|
||
|
||
。
|