Arco Design 项目贡献指南与技术规范详解

Arco Design 项目贡献指南与技术规范详解

arco-design A comprehensive React UI components library based on Arco Design 项目地址: https://gitcode.com/gh_mirrors/ar/arco-design

前言

Arco Design 作为一款优秀的企业级设计系统，其开源项目的健康发展离不开社区开发者的共同参与。本文将深入解析该项目的技术贡献规范，帮助开发者理解如何高效参与项目协作。

项目开发规范

语义化版本控制

Arco Design 严格遵循语义化版本控制（SemVer）规范：

• 主版本号（Major）：包含破坏性变更的版本更新
• 次版本号（Minor）：新增向后兼容的功能特性
• 修订号（Patch）：修复问题且不影响API的变更

这种版本控制方式确保了依赖管理的可靠性，每个重要变更都会记录在变更日志中。

代码提交规范

项目采用约定式提交规范（Conventional Commits），提交信息格式如下：

<类型>[可选范围]: <描述>

[可选正文]

[可选脚注]

常用提交类型包括：

• feat：新增功能
• fix：修复缺陷
• docs：文档变更
• style：样式调整
• refactor：代码重构
• perf：性能优化
• test：测试相关
• chore：构建/工具变更

开发环境配置

准备工作

1. 使用 Yarn 作为包管理工具（必须预先安装）
2. 项目初始化命令：yarn run init
3. 本地开发启动命令：yarn start

常用开发命令

# 启动开发服务器
yarn dev:site

# 代码质量检查
yarn eslint       # JavaScript检查
yarn stylelint    # CSS检查

# 文档生成
yarn docgen

# 代码格式化
yarn format

# 构建组件
yarn build

# 运行测试
yarn test

# 启动Storybook
yarn demo

组件开发规范

目录结构详解

每个组件都遵循标准化的目录结构：

components/组件名称/
├── README.*.md        # 自动生成的文档
├── __template__       # 文档模板
│   ├── index.*.md
├── __changelog__      # 变更日志（自动生成）
│   ├── index.*.md
├── __test__           # 测试相关
│   ├── __snapshots__  # 快照测试
│   ├── demo.test.ts   # 演示测试
│   └── index.test.ts  # 单元测试
├── __demo__           # 组件演示
│   ├── basic.md       # 基础用法
│   └── advanced.md    # 高级用法
├── index.tsx          # 组件入口
└── style              # 样式文件
    ├── index.less
    └── index.ts

组件文档规范

1. 文档模板位于 __template__ 目录
2. 使用特殊标记 %%Content%% 和 %%Props%% 作为占位符
3. 修改组件属性后，必须运行 yarn docgen 重新生成文档

演示代码规范

组件演示需要满足以下要求：

1. 代码块使用 tsx 语言标记
2. 每个演示代码都应该是完整可运行的
3. 推荐安装 TS in Markdown 插件获得更好的开发体验
4. 代码块中的 default export 将作为渲染内容

测试规范

项目采用全面的测试策略：

1. 单元测试：验证组件核心逻辑
2. 快照测试：防止UI意外变更
3. 性能考虑：本地运行完整测试可能消耗大量资源，建议：
   • 使用 yarn test:watch 针对特定组件测试
   • 通过CI流程获取完整测试结果

变更管理

1. 变更日志自动生成，开发者不应手动修改
2. 每次发布时，系统会自动更新变更日志
3. 重大变更需要在发布说明中特别标注

最佳实践建议

1. 分支策略：

   • 新功能开发使用 feature 分支
   • 问题修复直接提交到 main 分支

2. 代码审查：

   • 所有变更都需要通过Pull Request提交
   • 核心团队成员和社区贡献者采用相同的审查标准

3. 问题报告：

   • 提交问题前先搜索是否已有类似报告
   • 错误报告需包含最小复现代码
   • 功能请求需明确预期行为

通过遵循这些规范，开发者可以更高效地为 Arco Design 项目做出贡献，同时确保项目代码质量和维护性。

arco-design A comprehensive React UI components library based on Arco Design 项目地址: https://gitcode.com/gh_mirrors/ar/arco-design