云知声口语评测 SDK 文档工程 清晰、统一、方便查找的SDK文档，是提升客户服务质量的关键点之一。

借助git专业的版本管理能力和github的高可用性，特建此文档工程，将一应SDK的文档归总此处。

• 规范
• 版本说明文档
• 接口文档
• demo
• 流程保障
• 源代码提交流程中的文档维护
• 版本发布流程中的文档维护
• Android SDK
• API文档
• 功能规格文档
• 版本说明文档
• demo
• Javascript SDK
• API文档
• 评测输入输出说明

规范

版本说明文档

• 版本号为三段整数，前两段为需求，最后一段为debug
• SDK需要提供接口获取当前版本号
• 每个版本对应有feature和bugfix
• 每个版本有beta/release稳定状态标示
• 每一个代码提交必须对应一个版本号上升
• 每一个提交必须包含一个修改说明

接口文档

• 每个平台和编程语言的SDK API文档独立
• 不针对SDK版本单独维护文档，而是在每个接口中添加版本支持说明
• 修改API接口，应视为功能变化，对应的需上升版本号第一或第二段

demo

• 每个平台和编程语言应提供demo源代码
• 商务原因，此文档工程中，不提供整个可编译运行demo的工程下载
• demo源码中应穿插有SDK的使用说明注释
• demo对应有SDK的版本号

流程保障

文档撰写只是工作的开始，更多的工作需要保持文档的更新。尽量在流程增加保障，以期长期维护好文档。

源代码提交流程中的文档维护

1. push修改到SDK代码仓库

2. 触发pre-receive类型的Server-Side Hook

3. 检查SDK文档仓库中的/internal/commits中是否有对应说明 /internal/commits中每一行代表一个commit，格式为

   commit                                   sdk        ver    bugfix feature api   comment
   fad7305bfbebae5da57c4aa809785b6ce7400abe android    0.0.1  y      n       n     解决小米1s机型不能评测的问题；解决一些网络环境下出现oom的问题
   d77ba24ea1d646d5f56a132fc631835023e98ec2 iOS        0.1.0  n      y       y     增加本地mp3录音输出功能

   • ver 三断版本号的上升值
   • bugfix 是否为bug修正
   • feature 是否是增加新功能
   • api 是否需要更新api接口文档
   • comment 修正了什么bug或者增加了什么功能

4. 若步骤3的检查中格式不正确，push失败。需要更新/internal/commits后重新push

5. 若步骤3中标示需要更新api，则会检查对应的api文档是否有针对此commit的更新。如没有检测到有api文档更新，push失败。需要更新api文档后重新push

6. 若第一段或第二段版本号有更新，则在版本说明文档中自动插入最新版本的版本说明，并将该版本标示为beta状态

版本发布流程中的文档维护

1. 从开发发布到测试，在版本说明文档中增加版本号和对应的改动说明，此说明一般由提交记录自动整理而来；标示状态为beta
2. 从测试发布到项目经理，可以修改版本说明文档的内容(如增加测试报告等)，标示状态为release
3. 从项目经理发布到客户，需要基于release状态的版本做定制化构建(离线/appkey等)，文档不用单独准备，也不用更新，应直接取用次仓库中的文档