贡献指南 - jordium-gantt-vue3

July 1, 2025 · View on GitHub

感谢您对 jordium-gantt-vue3 项目的关注！我们欢迎社区的贡献，很高兴您能加入我们。

🌍 多语言版本

本文档提供多种语言版本：

📋 目录

行为准则
如何贡献
开发环境搭建
项目结构
编码规范
提交规范
Pull Request 流程
Issue 指南
测试
文档

📜 行为准则

本项目及其参与者均受我们的行为准则约束。通过参与，您需要遵守此准则。如发现不当行为，请报告至 ning.li@jordium.com / nelson820125@gmail.com。

我们的标准

相互尊重，包容多元化
协作建设，提供建设性意见
耐心待人，特别是对新手
考虑周全，理解不同观点
关注大局，以社区利益为重

🤝 如何贡献

您可以通过多种方式为 jordium-gantt-vue3 做贡献：

🐛 错误报告

首先搜索已有问题
使用我们的错误报告模板
提供清晰的重现步骤
包含环境详细信息

💡 功能建议

检查功能是否已存在
说明使用场景和好处
如可能提供原型图或示例

🔧 代码贡献

错误修复
新功能开发
性能优化
文档更新

📚 文档贡献

修复错别字或不清楚的内容
添加示例和教程
翻译文档
改进 API 文档

🛠️ 开发环境搭建

前置要求

Node.js: >= 16.0.0
npm: >= 8.0.0（或 yarn >= 1.22.0）
Git: 最新版本

克隆和设置

# 克隆仓库
git clone https://github.com/nelson820125/jordium-gantt-vue3.git
cd jordium-gantt-vue3

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 打开另一个终端运行演示
cd demo
npm run dev

可用脚本

# 开发
npm run dev              # 启动开发服务器
npm run dev:demo         # 启动演示开发服务器

# 构建
npm run build            # 生产环境构建
npm run build:lib        # 构建 npm 包

# 质量保证
npm run lint             # 运行 ESLint
npm run lint:fix         # 修复 ESLint 问题
npm run type-check       # TypeScript 类型检查
npm run format           # 使用 Prettier 格式化代码
npm run format:check     # 检查代码格式

# 测试
npm run test             # 运行单元测试
npm run test:watch       # 监视模式运行测试
npm run test:coverage    # 运行测试并生成覆盖率报告

📁 项目结构

jordium-gantt-vue3/
├── src/                     # 主要源代码
│   ├── components/          # Vue 组件
│   │   ├── GanttChart.vue   # 主甘特图组件
│   │   ├── Timeline.vue     # 时间轴组件
│   │   ├── TaskList.vue     # 任务列表组件
│   │   └── ...
│   ├── composables/         # Vue 组合式函数
│   │   ├── useI18n.ts       # 国际化
│   │   └── useMessage.ts    # 消息系统
│   ├── models/              # TypeScript 模型
│   │   ├── classes/         # 数据类
│   │   └── configs/         # 配置类型
│   └── styles/              # 全局样式
├── demo/                    # 演示应用
├── packageDemo/             # 包演示用于测试
├── docs/                    # 文档
├── tests/                   # 测试文件
└── ...

🎨 编码规范

代码风格

我们使用 ESLint 和 Prettier 来保持一致的代码风格：

缩进: 2 个空格
引号: 字符串使用单引号
分号: 不要求分号
行长度: 最大 100 字符
尾随逗号: ES5 风格

Vue.js 指南

<script setup lang="ts">
// 1. 导入放在最前面
import { ref, computed, onMounted } from 'vue'
import type { Task } from '../models/classes/Task'

// 2. Props 定义
interface Props {
  tasks: Task[]
  showToolbar?: boolean
}
const props = withDefaults(defineProps<Props>(), {
  showToolbar: true
})

// 3. Emits 定义
const emit = defineEmits<{
  taskUpdated: [task: Task]
}>()

// 4. 响应式数据
const isLoading = ref(false)

// 5. 计算属性
const taskCount = computed(() => props.tasks.length)

// 6. 方法
const handleTaskUpdate = (task: Task) => {
  emit('taskUpdated', task)
}

// 7. 生命周期钩子
onMounted(() => {
  // 初始化组件
})
</script>

<template>
  <!-- 使用语义化 HTML 和可访问性属性 -->
  <div class="gantt-container" role="application" aria-label="甘特图">
    <!-- 组件内容 -->
  </div>
</template>

<style scoped>
/* 使用 CSS 自定义属性进行主题化 */
.gantt-container {
  background: var(--gantt-bg-primary, #ffffff);
  color: var(--gantt-text-primary, #303133);
}
</style>

TypeScript 指南

严格模式: 启用严格的 TypeScript 检查
显式类型: 公共 API 优先使用显式类型注解
接口: 对象形状使用接口
枚举: 使用常量断言或联合类型代替枚举

// 好的做法
interface TaskOptions {
  id: number
  name: string
  assignee?: string
}

// 简单情况下更好的做法
type TaskStatus = 'pending' | 'in-progress' | 'completed'

// 使用泛型约束
function updateTask<T extends Task>(task: T): T {
  return { ...task, updatedAt: new Date() }
}

📝 提交规范

我们遵循约定式提交规范：

提交消息格式

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

[可选 正文]

[可选 脚注]

类型

feat: 新功能
fix: 错误修复
docs: 文档变更
style: 代码风格变更（格式化等）
refactor: 代码重构
perf: 性能优化
test: 添加或更新测试
chore: 维护任务

示例

feat(timeline): 添加缩放功能
fix(taskbar): 修复拖拽位置计算问题
docs(api): 更新 GanttChart 属性文档
style(components): 使用 prettier 格式化代码
refactor(composables): 提取公共逻辑到 useGantt
perf(timeline): 优化虚拟滚动
test(timeline): 为缩放功能添加单元测试
chore(deps): 更新 vue 到 3.4.0

范围指南

components: Vue 组件
composables: Vue 组合式函数
models: TypeScript 模型
styles: CSS/样式变更
timeline: 时间轴相关变更
taskbar: 任务条相关变更
i18n: 国际化
demo: 演示应用
build: 构建系统
ci: CI/CD 变更

🔄 Pull Request 流程

提交前

Fork 仓库
从 main 创建功能分支
进行变更
为新功能添加测试
更新文档
运行代码检查和测试
使用约定式提交格式提交

PR 检查清单

PR 模板

## 描述
变更的简要描述

## 变更类型
- [ ] 错误修复
- [ ] 新功能
- [ ] 破坏性变更
- [ ] 文档更新

## 测试
- [ ] 单元测试通过
- [ ] 手动测试完成
- [ ] 演示应用正常工作

## 截图（如适用）
在此添加截图

## 检查清单
- [ ] 代码遵循风格指南
- [ ] 完成自查
- [ ] 测试已添加/更新
- [ ] 文档已更新

🐛 Issue 指南

错误报告

使用错误报告模板并包含：

环境: 操作系统、浏览器、Node.js 版本
重现步骤: 清晰的编号步骤
预期行为: 应该发生什么
实际行为: 实际发生了什么
截图: 如适用
额外上下文: 其他相关信息

功能建议

使用功能建议模板并包含：

问题描述: 这解决了什么问题？
建议解决方案: 应该如何工作？
考虑的替代方案: 考虑过的其他方法
额外上下文: 原型图、示例等

🧪 测试

编写测试

// 单元测试示例
import { describe, it, expect } from 'vitest'
import { mount } from '@vue/test-utils'
import GanttChart from '../src/components/GanttChart.vue'

describe('GanttChart', () => {
  it('正确渲染任务', () => {
    const tasks = [
      { id: 1, name: '任务 1', startDate: '2025-01-01', endDate: '2025-01-05' }
    ]
    
    const wrapper = mount(GanttChart, {
      props: { tasks }
    })
    
    expect(wrapper.text()).toContain('任务 1')
  })
})

测试覆盖率

目标 80%+ 代码覆盖率
彻底测试 关键功能
包含 边界情况 和 错误场景
测试 可访问性 功能

📚 文档

代码文档

/**
 * 计算任务在时间轴上的位置
 * @param task - 包含日期信息的任务对象
 * @param startDate - 时间轴开始日期
 * @param dayWidth - 一天的像素宽度
 * @returns 包含左侧位置和宽度的对象
 */
function calculateTaskPosition(
  task: Task,
  startDate: Date,
  dayWidth: number
): { left: number; width: number } {
  // 实现
}

README 更新

添加新功能时：

更新功能列表
添加使用示例
更新 API 文档
如有 UI 变更包含截图

🌍 国际化

添加新语言

在 src/composables/useI18n.ts 中创建语言文件
为所有键添加翻译
使用新语言测试
更新文档

// 添加语言示例
const messages = {
  'zh-CN': { /* 中文翻译 */ },
  'en-US': { /* 英文翻译 */ },
  'fr-FR': { /* 法文翻译 */ }, // 新语言
}

🏷️ 发布流程

版本升级

我们使用语义化版本：

主版本: 破坏性变更
次版本: 新功能（向后兼容）
修订版本: 错误修复（向后兼容）

发布检查清单

📞 获取帮助

社区支持

GitHub Discussions: 一般问题和想法
GitHub Issues: 错误报告和功能请求
邮箱: ning.li@jordium.com / nelson820125@gmail.com

维护者响应时间

严重错误: 24 小时内
常规问题: 7 天内
功能请求: 14 天内
Pull Request: 7 天内

🙏 致谢

贡献者将会：

添加到贡献者列表
在发布说明中提及
在文档中给予荣誉

📄 许可证

通过为 jordium-gantt-vue3 做贡献，您同意您的贡献将在 MIT 许可证下授权。

感谢您为 jordium-gantt-vue3 做贡献！🎉

您的贡献让这个项目对每个人都变得更好。