# 贡献指南 感谢您对 KVideo 项目的关注!我们热烈欢迎任何形式的贡献,包括但不限于: - 🐛 报告 Bug - 💡 提出新功能建议 - 📝 改进文档 - 🎨 优化 UI/UX - ✨ 提交代码修复或新功能 ## 目录 - [行为准则](#行为准则) - [如何贡献](#如何贡献) - [报告 Bug](#报告-bug) - [提出功能建议](#提出功能建议) - [提交代码](#提交代码) - [开发指南](#开发指南) - [环境搭建](#环境搭建) - [代码规范](#代码规范) - [提交规范](#提交规范) - [Liquid Glass UI 设计规范](#liquid-glass-ui-设计规范) - [核心原则](#核心原则) - [组件设计准则](#组件设计准则) - [CSS 变量系统](#css-变量系统) - [动画规范](#动画规范) - [测试指南](#测试指南) - [文档规范](#文档规范) ## 行为准则 本项目遵循 [Contributor Covenant](https://www.contributor-covenant.org/) 行为准则。参与本项目即表示您同意遵守其条款。 我们承诺提供一个开放、友好、包容的社区环境: - 尊重不同的观点和经验 - 优雅地接受建设性批评 - 关注对社区最有利的事情 - 对其他社区成员保持同理心 ## 如何贡献 ### 报告 Bug 如果您发现了 Bug,请通过 [GitHub Issues](https://github.com/KuekHaoYang/kvideo/issues) 报告。报告时请包含: 1. **清晰的标题** - 简明扼要地描述问题 2. **重现步骤** - 详细说明如何触发 Bug 3. **预期行为** - 描述您期望的正常行为 4. **实际行为** - 描述实际发生了什么 5. **环境信息** - 浏览器版本(如 Chrome 120) - 操作系统(如 macOS 14.0) - Node.js 版本(如 20.10.0) 6. **截图/视频**(如适用) 7. **控制台错误**(如有) **Bug 报告模板:** ```markdown ### 问题描述 [清晰描述 Bug] ### 重现步骤 1. 进入 '...' 2. 点击 '...' 3. 滚动到 '...' 4. 看到错误 ### 预期行为 [描述预期的正常行为] ### 实际行为 [描述实际发生的情况] ### 截图 [如果适用,添加截图] ### 环境 - 浏览器: [如 Chrome 120] - 操作系统: [如 macOS 14.0] - Node.js 版本: [如 20.10.0] ### 额外信息 [任何其他有助于解决问题的信息] ``` ### 提出功能建议 我们欢迎新功能建议!请通过 [GitHub Issues](https://github.com/KuekHaoYang/kvideo/issues) 提交,并包含: 1. **功能概述** - 简要描述功能 2. **使用场景** - 说明为什么需要这个功能 3. **详细设计** - 描述功能如何工作 4. **UI 设计**(如适用)- 提供设计稿或草图 5. **技术实现思路**(可选) ### 提交代码 1. **Fork 仓库** ```bash # 点击 GitHub 页面右上角的 "Fork" 按钮 ``` 2. **克隆您的 Fork** ```bash git clone https://github.com/YOUR_USERNAME/kvideo.git cd kvideo ``` 3. **创建特性分支** ```bash git checkout -b feature/your-feature-name # 或 git checkout -b fix/your-bug-fix ``` 4. **安装依赖** ```bash npm install ``` 5. **进行开发** - 遵循 [代码规范](#代码规范) - 遵循 [Liquid Glass UI 设计规范](#liquid-glass-ui-设计规范) - 编写清晰的代码注释 6. **测试您的更改** ```bash npm run dev # 启动开发服务器 npm run lint # 检查代码规范 npm run build # 确保构建成功 ``` 7. **提交更改** ```bash git add . git commit -m "feat: 添加某个功能" # 遵循提交规范(见下文) ``` 8. **推送到您的 Fork** ```bash git push origin feature/your-feature-name ``` 9. **创建 Pull Request** - 前往原仓库页面 - 点击 "New Pull Request" - 填写 PR 模板 - 等待代码审查 ## 开发指南 ### 环境搭建 **系统要求:** - Node.js 20.x 或更高 - npm 9.x 或 pnpm 8.x - Git 2.x **快速开始:** ```bash # 克隆仓库 git clone https://github.com/YOUR_USERNAME/kvideo.git cd kvideo # 安装依赖 npm install # 启动开发服务器 npm run dev # 打开浏览器访问 http://localhost:3000 ``` ### 代码规范 #### TypeScript 规范 - **严格模式** - 启用 `strict: true` - **类型注解** - 所有函数参数和返回值必须有类型 - **避免 `any`** - 使用具体类型或 `unknown` - **接口优先** - 优先使用 `interface` 而非 `type` ```typescript // ✅ 好的示例 interface VideoProps { id: string; title: string; onPlay: (url: string) => void; } function VideoCard({ id, title, onPlay }: VideoProps): JSX.Element { return
{title}
; } // ❌ 不好的示例 function VideoCard(props: any) { return
{props.title}
; } ``` #### React 组件规范 - **函数组件** - 使用函数组件和 Hooks - **命名规范** - PascalCase 命名组件文件 - **单一职责** - 每个组件只做一件事 - **文件大小** - 单个文件不超过 150 行(严格遵守) - **Props 解构** - 在函数参数中解构 props ```typescript // ✅ 好的示例 - SearchForm.tsx 'use client'; interface SearchFormProps { onSubmit: (query: string) => void; placeholder?: string; } export function SearchForm({ onSubmit, placeholder = '搜索视频...' }: SearchFormProps) { // 组件逻辑(不超过 150 行) } ``` #### 文件组织规范 ``` components/ ├── search/ # 功能分组 │ ├── SearchForm.tsx # 主组件 │ ├── VideoGrid.tsx │ └── index.ts # 导出文件 ├── player/ └── ui/ # 通用 UI 组件 ├── Button.tsx ├── Card.tsx └── Input.tsx ``` #### 命名规范 | 类型 | 规范 | 示例 | |------|------|------| | 组件 | PascalCase | `VideoPlayer`, `SearchForm` | | 函数 | camelCase | `handleSearch`, `fetchVideoData` | | 常量 | UPPER_SNAKE_CASE | `API_BASE_URL`, `MAX_RESULTS` | | 接口 | PascalCase + 描述性 | `VideoPlayerProps`, `SearchResult` | | 类型 | PascalCase | `VideoData`, `PlayerState` | | Hook | use + PascalCase | `useVideoPlayer`, `useSearchCache` | ### 提交规范 我们遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范: **格式:** ``` ():