中文|English

介绍

Ascend Samples，欢迎各位开发者！

贡献要求

开发者提交的修改的工程文件中至少包括源码、readme、编译&运行脚本，并遵循以下标准。

请贡献者在提交代码之前签署CLA协议，“个人签署”，链接。

一、源码

1. 在线编译,推理请使用C++/python代码实现，符合第四部分编码规范(当前只有C++的样例)

2. C++PR 提交样例规范请参考sample。

3. 贡献者工程代码目录规则：

   • 工程目录下有 src 文件夹，用于存放源码。
   • 工程目录下有 readme (*.md 格式的文件)。
   • samples的目录下st的文件夹中放置用户testcase测试脚本,cplusplus下放置C++工程的测试脚本，python文件夹下放置python工程的测试脚本。命名规则要求为testcase_ + "工程名称" + .sh，其中，工程名称为对应工程的src文件夹上一级目录名。
     以C++ YOLOV3_coco_detection_picture样例为例：
     样例src目录为： samples/cplusplus/level2_simple_inference/2_object_detection/YOLOV3_coco_detection_picture/src
     因此样例testcase的脚本为： st/cplusplus/testcase_YOLOV3_coco_detection_picture.sh

   说明：

   • 每一个入口脚本对应两种设备形态，要求当前工程适配这两种设备形态：Atlas200dk，A300-3010。
   • 每一个设备形态对应一种或多种版本，要求当前工程至少适配一种版本。
   • 当前测试环境存在版本为：1. CANN 5.0.3.alpha005的Atlas200dk和A300-3010。 2. CANN 5.0.4.alpha002。
   • 注意：blacklist_version.conf中的内容为黑名单版本，即不会在该版本上跑该testcase。如testcase_YOLOV3_coco_detection_picture: 5.0.3.alpha005

4. 从其他开源迁移的代码，请增加License声明。

二、License规则

需要根据您签署的CLA类型进行声明：
CLA签署网站：https://clasign.osinfra.cn/sign/Z2l0ZWUlMkZhc2NlbmQ=
CLA包括企业签署、员工签署、个人签署三类，非华为员工签署个人，并根据自己签署的类型声明对应的copyright
所有的新建源码文件(cpp、py、h等文件)需要支持Apache 2.0 License，并在源码文件头部增加如下声明，将[yyyy]替换为代码创建的4位数年份，将[name of the copyright owner]替换为所在组织的名字（所有个人签署CLA一律声明Huawei Technologies Co., Ltd），注意删除方括号：

# Copyright [yyyy] [name of copyright owner]
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License. 

所有从其他源码修改而来的代码，不要改变源代码中的LICENSE类型，如果源码中已有其它公司的Copyright，原有的copyright声明保持不变，在上面增加一行Copyright，将[yyyy]替换为修改代码的4位数年份，将[name of the copyright owner]替换为本人所在组织的名字（所有个人签署CLA一律声明Huawei Technologies Co., Ltd），注意删除方括号。
例如：

# Copyright [yyyy] [name of copyright owner]
# Copyright 2018 hisillion Technologies Co., Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

三、readme

readme用于指导用户理解和部署样例，要包含如下内容：

1. 简介：

   工程项目的功能和运行方法、模型的来源；

2. 关键要求：

   1. 提交的工程项目的功能：包含样例的输入和输出;
   2. 环境变量设置，依赖的第三方软件包和库，以及安装方法；
   3. 工程文件获取方法：下载工程文件压缩包或是git clone；
   4. 模型如何从modelzoo仓下载；
   5. 模型转换得到的离线模型对输入数据的要求；
   6. 测试数据(bin文件，图片，视频)请提供归档OBS、网盘链接;
   7. 将原始模型转换为Davinci模型的模型转换命令；
   8. 工程编译步骤以及工程运行步骤；
   9. 推理后的校验方法 (校验方法以shell脚本或是python脚本提供)

四、PR提交规范

提交PR操作可以参考如何fork仓库并提交PR_wiki。

PR提交的样例需要包含门禁项、工程测试用例和readme。

1. 简介：

   • 提交的PR中应该包含如下文件， 这是校验PR提交是否有效的门禁项：

     1. 工程目录下有 src 文件夹，用于存放源码。
     2. 工程目录下有 readme (*.md 格式的文件)。
     3. st目录下有testcase*.sh (样例功能测试脚本)

   • 提交PR后，会自动触发门禁流水，后台会根据用例入口shell(st目录下对应编程语言文件夹中的testcase*.sh)进行编译，关键要求如下：

     1. 提交的PR中的文件不能包含 rm 删除命令；
     2. 提交的PR中不应上传原始模型文件和转换后的Davinci模型；
     3. 提交的PR中不应上传测试集和验证集;

2. st目录下对应编程语言文件夹中的testcase*.sh 应该包含推理和校验推理的结果的功能，具体释义如下：

   推理阶段包含：

   • 下载测试集和验证集。
   • 下载原始模型文件。
   • 设置模型转换所需的环境变量。
   • 使用atc命令进行模型转换。
   • 根据自己提交的工程配置工程编译时所需的环境变量。
   • 配置程序运行所需的环境变量。
   • 运行程序。

   校验推理的结果(根据不同的工程提供不同的推理结果校验方法，校验方法可以写在脚本中)：

   • 当推理阶段发生成错误时 返回 inferenceError。
   • 当推理结果校验阶段发生成错误时 返回 verifyResError。
   • 如果两个阶段执行都成功 最后返回 success。

3. 执行环境已预装软件包和Python3.6.9环境，调用命令"python3.6"、，安装第三方库依赖使用"pip3 install package --user"、"python3.6 -m pip install package --user"均可。

4. 模型需要按照 modelzoo仓的贡献指南，上传到modelzoo中。验证文件(bin、图片、视频)请提供归档OBS、网盘链接或联系管理员存放到固定的obs地址，不要放在samples仓中。

5. 环境和其他问题，请提交Issue跟踪。

6. 提交测试用例可以参考PR提交示例。

五、编程规范

• 规范标准

  1. C++代码遵循google编程规范：Google C++ Coding Guidelines；单元测测试遵循规范： Googletest Primer

  2. Python代码遵循PEP8规范：Python PEP 8 Coding Style；单元测试遵循规范： pytest

• 规范备注

  1. 优先使用string类型，避免使用char*；
  2. 禁止使用printf，一律使用cout；
  3. 内存管理尽量使用智能指针；
  4. 不准在函数里调用exit；
  5. 禁止使用IDE等工具自动生成代码；
  6. 控制第三方库依赖，如果引入第三方依赖，则需要提供第三方依赖安装和使用指导书；
  7. 一律使用英文注释，注释率30%--40%，鼓励自注释；
  8. 函数头必须有注释，说明函数作用，入参、出参；
  9. 统一错误码，通过错误码可以确认哪个分支返回错误；
  10. 禁止出现打印一堆无影响的错误级别的日志；
  11. 注释的代码如果没有特别用处，全部删掉，严禁通过注释的方式删除无用代码；