Skip to content

Latest commit

 

History

History
150 lines (112 loc) · 5.53 KB

contribute.md

File metadata and controls

150 lines (112 loc) · 5.53 KB

协作开发规范

具体包含功能模块层级设计、代码分支管理、代码合并方式、代码审核方式、版本管理和待解决问题和待实现功能管理。

功能模块

最终形成功能的代码层级：

可执行

  1. 所有分析功能，各自形成一个可执行文件，每个可执行维护自己的README.md
  2. 采集功能形成两个可执行文件，
    • jsirun，进行程序执行采集，功能差异以命令行参数区分；
    • jsi-xxx，进行编译插装，编译插装使用编译器区分指令，例如：jsi-gcc
  3. 压缩功能形成一个可执行文件，功能差异以命令行参数区分

新增库

新增库需求需例会讨论。

  1. 采集部分：
    • 一个库插装一个库
    • 一个加速器一个库
    • 编译插桩一个库（LLVM，插桩函数）
  2. 存储部分：
    • 压缩与解压缩
    • 统一访问接口
  3. 分析不形成库

头文件

  1. 采集与存储模块头文件应放于jsi-toolkit/include目录下
  2. 分析放在jsi-toolkit/tool/analysis目录下对应的功能目录下
  3. 头文件应仅包含需要暴露的接口
  4. 宏定义应位于各自的.h文件下
  5. 添加防止重复编译和重复预加载的宏定义，例如：
#ifndef __JSI_RECORD_DEFINES_H__
#define __JSI_RECORD_DEFINES_H__
...
...
#endif

类

  1. 对一种功能模块来讲，需要对外提供一个接口类
  2. 对于一类具有相似功能的模块（例如时间线对齐），需要实现一个对应接口类
  3. 类管理的数据尽量使用private，通过public接口访问

代码分支

  1. 每个功能开发创建一个分支（功能施工图，动态增加）
  2. 每个bug修复创建一个分支
  3. 每个issue开发创建一个分支
  4. 每次开发之前与主分支同步，及时解决冲突
  5. 代码merge之后删除分支
  6. 每个稳定版本要有一个release分支（半年/项目周期）

代码审核与合并

  1. 代码合并需要编译成功、测试成功，后提交PR并解决代码冲突，PR格式：
    • 开发功能简述
    • 文件改动简述（数据格式、函数接口、参数修改）
    • 与本功能相关的其他代码的bug修复简述（关联已有issue，或新建issue说明bug）
  2. 审核选择对应开发内容负责博士生+游心+宣智博，需2人以上审核
  3. 审核完成后进行代码合并，选择Squash

版本管理

  1. 每6月（项目周期）更新大版本号
  2. 每功能更新中版本号
  3. 每PR更新小版本号

Issue

  1. 发现bug并修复后，修复完成后随PR补充一个issue
  2. 发现无法修复的bug后，提一个issue详细描述bug复现方法
  3. Todo提一个issue，添加相应标签（feature、doc）

代码测试

代码测试需要在每次提交PR前完成，包括工具编译、功能测试等

测试要求

  1. 编译通过
  2. 完成单节点与集群测试
  3. 保留测试代码
  4. 保留测试结果文档

测试管理

  1. 整体回归测试每3个月或中版本号更新时进行一次
  2. 测试代码与测试结果文档保存在**/JSI-Toolkit/test/功能名称/姓名_日期**（例如：/JSI-Toolkit/test/trace/xzb_20240404）下
  3. 测试文档简洁明了为主，可以为.docx或.md，可以添加截图

命名规范

  1. 对应命名按照其功能英文命名
  2. 函数与变量采用驼峰命名法（myFunction）
  3. 类名称采用大驼峰命名法（MyClass）
  4. 宏命名全大写，以JSI_开头
  5. 宏函数换行缩进

代码注释

  1. 中英文均可
  2. 新文件文件开始写明文件内容
  3. 接口函数写明字段定义与函数功能定义
  4. 模板函数列出具体对应类型的描述（枚举等）
  5. 重要算法步骤简述
  6. 下载并使用doxygen插件，便于后续注释生成

文档

开发文档

  1. 阐明文件功能与功能模块核心方法（涉及指标）
  2. 阐明接口参数定义和对应功能

使用文档

  1. 可执行文件的每个参数的详细说明
  2. 预期结果与结果文件字段解释

附录-类谷歌命名规范

  1. 文件名应该使用小写字母，并使用下划线分隔单词。
  2. 类型名称（类、结构体、枚举、类型别名）使用大驼峰命名法（Upper Camel Case）。
  3. 变量（包括函数参数、局部变量、成员变量）使用小驼峰命名法（Lower Camel Case），并以下划1. 线开头。
  4. 常量名使用全大写字母，并用下划线分隔单词。
  5. 枚举的命名应该包含其类型名称，并且枚举值应该使用大写字母。
  6. 使用4个空格进行缩进。
  7. 函数体和类定义应该有一个大括号的新行。
  8. 如果一个构造函数或析构函数有函数体，它们应该在大括号内有一个空行。
  9. 函数长度应该保持在合理范围内，通常不超过 40 行。
  10. 函数应该只做一件事情，并做好。
  11. 使用 // 进行单行注释，使用 /* */ 进行多行注释。
  12. 文件、类、函数和重要的代码块应该有注释说明其作用。
  13. 头文件应该有包含保护，以防止多重包含。
  14. 头文件应该包含尽可能少的代码，主要是声明。
  15. 源文件应该包含实现细节，并且每个源文件应该只包含一个类的定义。
  16. 使用 namespace 来避免全局命名空间的污染。
  17. 命名空间应该有一个一致的命名约定。
  18. 避免使用宏，除非没有更好的替代方案。
  19. 如果使用宏，应该使用大写字母，并用下划线分隔单词。
  20. 使用 const 或 constexpr 来声明常量，而不是使用 #define。
  21. 使用异常来处理错误，而不是返回错误代码。