Skip to content

Latest commit

 

History

History
239 lines (166 loc) · 8.31 KB

SPECIFICATION.md

File metadata and controls

239 lines (166 loc) · 8.31 KB
Raw

Lego组件规范

@(基础能力)

###1 组件规范

####1.1 命名规范 在团队代码规范的前提下，组件开发需要遵循的规范如下:

1.文件和目录名字包含[a-z\d-]，并以英文字母开头

2.单词简洁明了优先，组件命名长度不超过15个字符长度(FIS插件除开标配字符串不能超过15个字符长度)，除非必要，不允许“.js”命名组件

3.自定义属性多单词之间用“-”连接，并加上自定义分类开头，诸如：data api 命名为小写并用连字符，如 data-courseid

4.事件名为驼峰：自定义事件，用于组件通信等场合

5.常量命名规则[A-Z\d-]，并以英文字母开头

6.变量以及单例模块采用驼峰，并以小写字母开头 moduleName，className

7.类名（多例）采用驼峰，并且首字母要大写 ClassName

####1.2 目录规范 组件历史版本号 组件历史版本号，采用MAJOR.MINOR.PATCH格式，版本号永远递增

  • 0.0.1 内测版本
  • 1.0.0 初始稳定版本
  • 1.0.1 补丁版本，向后兼容的bug fix版本
  • 1.1.1 小版本，向后兼容并增加功能
  • 2.1.0 大版本，具有向后不兼容的API变化版本

组件文件目录结构

—— edu-mobile

———— docs markdown 文档，除了 README 的其他文档

—————— edu-mobile.md

———— examples 演示 markdown

—————— images 例子中如果有用到 img 等资源时，存放在该目录

———————— test.png

—————— css 例子中使用到的css文件

—————— js 例子中使用到的js组件

—————— examples.md

———— src 存放 js, css 文件等源文件（子目录文件夹不做严格要求）

—————— img 存放组件用到的 img 等文件

———————— sprite.png

———————— sprite.psd

—————— edu-mobile.css

—————— edu-mobile.js

—————— edu-mobile.tpl

———— tests 单元测试/自动化测试存放目录

—————— edu-mobile-spec.js

———— lego_modules lego install 生成，存放依赖的其他组件

———— HISTORY.md 版本更新说明

———— README.md 组件总体说明

———— package.json 版本等元信息

———— .gitignore git 忽略某些文件

####1.3 开发规范 组件接口
组件接口提供组件Init方法，作为自动化文档工具调用

组件CSS UI组件的样式按照前面的文件目录规范。组件支持公共样式。同时，支持自定义样式参数 ---css :

  • css文本
  • css文件路径

代码规范

代码规范

####1.4 文档规范 文档说明 文档以markdown格式，每个组件必须存在README.md文件，用来描述组件。

# 组件名称

-----

组件功能介绍。

-----

## 依赖说明

该模块依赖哪些组件，可以在这里描述清楚

## 使用说明

如何使用该组件，可以根据组件的具体特征，合理组织。

## API

需要提供 API 说明，属性、方法、事件、返回值等说明。

历史版本说明 文档根目录下需要有文档版本更新说明。用来描述组件更新版本。最新的版本在最上面

# History

### 1.1.0[MAJOR.MINOR.PATCH]

* [PATCH] #10（对应的issue连接） 修复了 XXX 问题
* [PATCH] #20 修复了 YYY 问题
* [NEW] #30 增加了 ZZZ 功能，不涉及API改动
* [MINOR] 涉及到兼容性变化API，诸如删除了一个参数
* [MAJOR] 新增了一个API
* [IMPROVED] 接口增强、健壮性和性能提升、代码优化、依赖模块升级等。
* [TODO] 已知的需要做的/需要解决的问题

### 1.0.0

* [NEW] 第一个版本/新增了一个版本

其他文档 如果涉及到其他的一些分析文档，移到docs目录下，在README.md中增加连接，另外，其他子目录下，如有必要，也需要对应的README.md文件。

###2 流程规范

####2.1 组件官网

组件提交的源站：内部源、外部源

####2.2 组件流程

在业务开发过程中，流程参照如下：

其中组件开发、反馈、审核、认证等规范详见后续。

###3 开发组件 开发一个组件，工具上线之后参照spm机制

###4 组件维护 ####4.1 组件审核 内部组件 内部组件主要是针对业务相关，不能开源的一些组件。组件需要提交到内部源：lego.imweb.io。 组件开发完成之后，由IMWEB技术评审会进行组件Review，Review List如下：

  • 组件目录是否符合规范
  • 组件命令是否符合规范
  • 组件READEME.md等说明等文档是否完善
  • 组件开发/注释是否符合规范
  • 组件依赖资源是否合理
  • 组件API是否合理
  • 组件安全检测是否合规
  • 组件DEMO/自动化测试用例是否完备 组件修改，涉及到一些版本提交组件，需要报备技术评审会进行Review，处理必要的Review之外，还需要如下：
  • History.md是合规
  • 此次版本变更是否合规
  • 修改对应的issue等是否合规

外部组件 外部组件，即可以开源的组件，代表了团队对外的一些技术产出。需要遵循：

  • 外部组件需要先经过内部组件提交并审核通过
  • 内部组件提交之后，报备技术评审会进行审核是否可以开源
    • 报备人需要准备开源目的、价值
    • 开源是二次开发还是原创的说明
    • 二次开发需要备注源代码出处
  • 审核开源组件的贡献支持者
  • 开源组件由统一接口人同步到团队开源并注明贡献者
  • 需要注明开源贡献途径

外部组件贡献 外部开发者提供的组件，会首先进入待审核的组件库，IMWEB技术会定期（每周四）对外部组件贡献者进行审核，审核原则按照内部组件审核原则，并给予组件贡献者反馈和修改重新提交途经。

####4.2 组件认证 组件认证机制 组件认证基于组件使用者对组件的评价，通过认证的组件何可以放心提供使用，并且认证组件可以得到快速的issue响应和支持。

  • 可用通过站点查看到认证组件的标识
  • 认证具有认证级别和认证说明
  • 在使用组件的时候，可以凭借认证来对组件使用给予不同的信任
  • 要得到组件认证，需要有另外提交组件认证，会专门进行组件认证流程
    • 必须是通过组件审核的组件
    • 组件认证需要从更多方面对组件更细致的Reveiw(代码级别)
    • 对组件进行性能、使用场景等方便的Reivew
  • 组件认证级别到每行代码的必要性
  • 组件认证对文档、DEMO场景、测试用例有更高的要求
  • 获得组件认证的组件，如果用户普片反馈不好，会对组件进行降级处理
  • 需要认证组件依赖的组件是否都合理且均为获得认证的组件

组件认证步骤 需要组件认证的组件，贡献者在组件平台提交认证申请，由IMWEB技术评审会对组件进行组件认证，组件认证提交的信息如下：

  • 组件的名字
  • 组件贡献者
  • 组件的介绍
  • 线上项目的URL
  • 用户访问的量级
  • 兼容性支持情况
  • Demo/测试用例
  • 承诺维护支持

组件反馈机制 组件提交之后，组件下载使用者可以通过反馈组件使用情况来对组件进行评分以及issue提交，以完备组件的使用以及使用场景。

  • 可以通过开源站点上面的反馈入口来提交反馈组件
  • 反馈组件的bug、场景、issue等
  • 组件被依赖的次数，也会作为组件反馈的一种机制

####4.3 经验沉淀 问题沉淀