README.md
云知声口语评测 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的版本号
流程保障
文档撰写只是工作的开始,更多的工作需要保持文档的更新。尽量在流程增加保障,以期长期维护好文档。
源代码提交流程中的文档维护
-
push修改到SDK代码仓库
-
触发pre-receive类型的Server-Side Hook
-
检查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或者增加了什么功能
-
若步骤3的检查中格式不正确,push失败。需要更新/internal/commits后重新push
-
若步骤3中标示需要更新api,则会检查对应的api文档是否有针对此commit的更新。如没有检测到有api文档更新,push失败。需要更新api文档后重新push
-
若第一段或第二段版本号有更新,则在版本说明文档中自动插入最新版本的版本说明,并将该版本标示为beta状态
版本发布流程中的文档维护
- 从开发发布到测试,在版本说明文档中增加版本号和对应的改动说明,此说明一般由提交记录自动整理而来;标示状态为beta
- 从测试发布到项目经理,可以修改版本说明文档的内容(如增加测试报告等),标示状态为release
- 从项目经理发布到客户,需要基于release状态的版本做定制化构建(离线/appkey等),文档不用单独准备,也不用更新,应直接取用次仓库中的文档