• AI+Net 开源社区建设方案
• • 一、项目平台
  • 二、项目代码
  • • 1. 目录结构
    • 2. 代码内容
  • 三、版本控制
  • 四、开源数据
  • 五、社区维护
  • 五、帮助文档（Optional）
  • • 主要内容
    • 文档结构
    • 参考方案

AI+Net 开源社区建设方案

依托鹏城实验室iHub系统建立AI+Net的开源社区，吸引国内和国际的一流团队共享相关源代码和数据，搭建一个有世界级影响力的平台

一、项目平台

同时使用iHub+Github对项目文件进行管理

• 在iHub上建立开源项目，汇集相关代码与数据，作为开源社区主站点，iHub用户手册可参考：https://code.ihub.org.cn/user_helps/1

• 在GitHub上建立相同的开源项目，保持更新，用于备份，作为开源社区副站点，GitHub使用手册可参考：https://docs.github.com/cn

以上两平台均基于Git分布式版本控制系统，使用方式很接近，可无缝衔接

二、项目代码

1. 目录结构

团队/项目负责人各自收集并整理与AI+Net相关的代码

• 整个AI+Net项目需要几位总负责人（一级负责人），负责维护整个AI+Net开源项目的项目空间，例如：在iHub上申请项目空间、维护整个项目代码的目录结构，统一代码整理规范、文档编写规范，与各个子项目/子课题负责人对接等等
• 每个子项目/子课题有自己的负责人（二级负责人），负责整理、统筹整个子项目/子课题内所有project的代码整理、文档编写等等，与总负责人对接。
• 对于每个子项目/子课题内具体的project，各位教授/博后/博士生作为主要贡献者，负责整理具体的代码、demo、文档等，整理好后同步至项目空间。

以下为一个示例：

AI+Net项目空间 （一级负责人）
├─ 课题1-智能接入网（二级负责人）
│    └─ file_placeholder
│    └─ ...
├─ 课题2-智能传输网（二级负责人）
│    └─ file_placeholder
│    └─ ...
├─ 课题3-智能核心网（二级负责人）
│    └─ file_placeholder
│    └─ ...
├─ 课题4-网络智能服务（二级负责人）
│    └─ file_placeholder
│    └─ ...
└─ 课题5-数据与模型驱动（二级负责人）
      └─ 模型1: 基于深度强化学习的负载均衡模型（Project贡献者）
            ├─ main.py
            ├─ model
            │    └─ file_placeholder
            │    └─ ...
            ├─ output
            │    └─ file_placeholder
            │    └─ ...
            ├─ readme.md
            └─ utils
            ├─ environment
            └─ gen_fig
            └─ ...
      └─ 模型2: 基于高斯过程的流量预测模型（Project贡献者）
            └─ ...
      └─ 模型3: xxx
      └─ ...

上述示例中，一级负责人需申请+维护整个项目空间、二级负责人需维护整个课题相关的代码整理、Project贡献者需自行整理好模型相关的代码、demo和说明文档，上传至项目空间。模型上传后，贡献者通知二级负责人，二级负责人将检查模型代码是否齐全，是否可运行，文档是否详尽等；二级负责人检查完毕后通知一级负责人，一级负责人将针对性更新整个项目空间的文档说明，例如：2020/11/08日，课题5新增模型xxx等。

2. 代码内容

在梳理模型相关代码时，主要注意以下几点：

1. 梳理代码目录结构
   • 主文件与功能模块文件分开，便于维护与二次开发
   • 删除非必要文件（如废弃的模块文件、中间文件、临时数据等），保证代码文件的整洁与清晰
2. 加上必要的代码注释
   • 关键函数标注好输入输出格式与设计逻辑
   • 文件开头可加入Header，如开发者/负责人、维护内容、建立时间、Copyright等
3. 提供可运行的demo
   • 各个项目须提供一个可运行的demo，确保代码文件有效
   • 在demo中展示关键函数/关键功能的用法
4. 撰写帮助文档
   • 各个项目须提供一个较详细的readme文件，描述代码文件结构与主要代码文件的使用方法
   • readme文件统一使用markdown撰写，保持内容与格式的简洁

三、版本控制

iHub与Github均使用Git分布式版本控制系统，因此项目统一使用Git进行代码的版本控制，Git的使用可参考：https://git-scm.com/

注意：master分支为主要分支，项目成员进行二次开发应新建一个branch分支，在branch分支上测试通过后再与master分支进行merge操作，避免直接对master分支进行修改并推送

四、开源数据

除了项目代码之外，项目所依托的数据也可视情况开源，开源数据的影响力或许大于开源代码

• 开源数据可整理至一个单独的 Dataset 文件夹，编纂好数据说明文档，包括数据存储格式、涵盖信息等

五、社区维护

Github上用户可以在issue页面抛出项目代码的相关问题，如代码运行报错信息、算法配置问题等等。项目开发人员须定期处理issue，修复项目bug，并在项目首页同步update信息，保持AI+Net 开源项目的生命力。

iHub似乎目前并未提供类似的社区交流功能，可以反馈给开发团队，目前社区维护可以通过Github上建立的副站点项目进行

五、帮助文档（Optional）

为提升AI+Net开源项目的影响力、开源代码的可读性与开源社区的活跃度，建议AI+Net项目维护一个较为详细的项目介绍+帮助文档

主要内容

• 帮助文档的一级类目可包含：AI+Net项目设立背景、AI+Net项目资源列表、AI+Net所涵盖的项目方向、AI+Net项目主要负责人与联系方式等总体项目信息

AI+Net开源社区项目可指派几位一级类目文档负责人，负责撰写一级类目文档的相关内容，对二级类目的文档进行分类与整理，并检验文档规范等

• 帮助文档的二级类目为各个子项目的文档，可包含：各个子项目的主要背景、方案思路及项目代码使用说明等，帮助用户新手快速上路
  • 二级类目文档可加入必要的公式与图表，帮助用户理解相关算法。具体内容可参考子项目所关联的参考文献（如已发表的论文与专利等）
  • 二级类目文档可提供参考文献的引用/访问信息（如已发表论文的bib信息等），方便用户进行拓展阅读

AI+Net子项目的负责团队可指定子项目文档的负责人，维护各自的子项目文档

文档结构

帮助文档的内容结构可与代码空间的目录结构相对应，以下为示例：

AI+Net项目帮助文档 （一级负责人）
├─ 课题1-智能接入网（二级负责人）
│    └─ file_placeholder
│    └─ ...
├─ 课题2-智能传输网（二级负责人）
│    └─ file_placeholder
│    └─ ...
├─ 课题3-智能核心网（二级负责人）
│    └─ file_placeholder
│    └─ ...
├─ 课题4-网络智能服务（二级负责人）
│    └─ file_placeholder
│    └─ ...
└─ 课题5-数据与模型驱动（二级负责人）
      └─ 模型1: 基于深度强化学习的负载均衡模型（Project贡献者）
            ├─ 模型背景+方案思路+代码使用说明
      └─ 模型2: 基于高斯过程的流量预测模型（Project贡献者）
            ├─ 模型背景+方案思路+代码使用说明
      └─ 模型3: xxx
      └─ ...

参考方案

• iHub似乎并未提供文档功能，目前推荐使用ReadtheDocs进行文档管理

• 这里提供一个基于ReadtheDocs的Reinforcement Learning开源项目文档供参考：https://garage.readthedocs.io/en/latest/# ，对应的Github项目为：https://github.com/rlworkgroup/garage