Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
457 lines (318 loc) · 12.7 KB

CONTRIBUTING.md

File metadata and controls

457 lines (318 loc) · 12.7 KB

贡献指南

感谢您考虑为 MoeCopy AI 做出贡献！我们欢迎各种形式的贡献，包括代码改进、Bug 修复、文档完善和翻译贡献。

贡献方式

🌍 翻译贡献

我们非常欢迎帮助改进现有翻译或添加新语言支持！MoeCopy AI 目前支持简体中文和英语，包含 452 个翻译键。

反馈翻译问题

如果您发现翻译不准确、不通顺或有更好的表达方式：

  1. 在 GitHub Issues 创建 issue
  2. 使用 "translation" 标签
  3. 在 issue 中说明：
    • 翻译键名（如 batch.filter.title）
    • 当前翻译
    • 建议的翻译
    • 出现位置或上下文说明

Issue 示例:

标题: [Translation] 改进批量抓取过滤器标题翻译

翻译键: batch.filter.title
当前翻译: "过滤"
建议翻译: "链接过滤"

原因: 当前翻译过于简短，不清楚是过滤什么。建议改为"链接过滤"更明确。
出现位置: 侧边栏 > 批量抓取 > 过滤器面板标题

提交翻译 PR

如果您熟悉 Git 和 GitHub，可以直接提交 Pull Request 修复翻译：

快速步骤:

  1. Fork 项目到您的 GitHub 账号
  2. 克隆到本地: git clone https://github.com/YOUR_USERNAME/moe-copy-ai.git
  3. 从 dev 分支创建翻译分支: git checkout -b fix/translation-zh-xxx
  4. 编辑翻译文件:
    • 简体中文: locales/zh_CN.json
    • 英语: locales/en_US.json
  5. 重要: 保持两个文件的键一致（不要删除或重命名键）
  6. 确保 JSON 格式正确（可使用 pnpm run format）
  7. 提交更改: git commit -m "fix: improve translation for xxx"
  8. 推送到您的 Fork: git push origin fix/translation-zh-xxx
  9. 创建 PR 到 dev 分支（不是 main）
  10. 在 PR 描述中说明修改的翻译键和原因

PR 注意事项:

  • ✅ 只修改翻译文件（locales/*.json），不要改动代码
  • ✅ 确保 zh_CN.json 和 en_US.json 的键完全一致
  • ✅ 使用 Prettier 格式化 JSON 文件
  • ✅ 提交消息使用英文，格式为 fix: improve XXX translation
  • ❌ 不要修改键名或删除现有的键
  • ❌ 不要在一个 PR 中混入无关的修改

详细翻译贡献指南: 查看 i18n 开发者指南，包含：

  • 翻译文件结构说明
  • 完整的 PR 提交流程
  • 添加新语言的步骤
  • 本地测试方法

添加新语言

想为 MoeCopy AI 添加新语言支持（如日语、韩语、法语）？

步骤概览:

  1. 创建新的翻译文件（如 locales/ja_JP.json）
  2. 更新类型定义 (utils/i18n/types.ts)
  3. 更新翻译加载逻辑 (utils/i18n/translations.ts)
  4. 测试语言检测和切换
  5. 提交 PR

详细步骤: 请查看 i18n 开发者指南 - 添加新语言 章节。

🐛 Bug 报告

发现 Bug？请在 GitHub Issues 提交，包含以下信息：

  • 问题描述: 清晰描述遇到的问题
  • 复现步骤: 详细的复现步骤（1. 2. 3. ...）
  • 预期行为: 您期望发生什么
  • 实际行为: 实际发生了什么
  • 环境信息:
    • 浏览器版本（如 Chrome 120）
    • 扩展版本（如 v0.2.1）
    • 操作系统（如 Windows 11, macOS 14）
  • 截图或日志: 如果适用，提供截图或控制台错误信息

✨ 功能请求

有新功能想法？欢迎在以下渠道分享：

好的功能请求应包含:

  • 问题描述: 您想解决什么问题？
  • 解决方案: 您希望如何解决？
  • 替代方案: 是否考虑过其他方法？
  • 使用场景: 典型的使用场景示例

💻 代码贡献

开发环境设置

前置要求:

  • Node.js 18+
  • pnpm 8+ (推荐) 或 npm

安装步骤:

# 1. Fork 并克隆项目
git clone https://github.com/YOUR_USERNAME/moe-copy-ai.git
cd moe-copy-ai

# 2. 安装依赖
pnpm install

# 3. 启动开发服务器
pnpm dev

# 4. 在浏览器中加载扩展
# - 打开 Chrome，访问 chrome://extensions/
# - 启用"开发者模式"
# - 点击"加载已解压的扩展程序"
# - 选择 build/chrome-mv3-dev/ 目录

开发流程

1. 创建功能分支

# 从 dev 分支创建新分支
git checkout dev
git pull origin dev
git checkout -b feat/your-feature-name

分支命名规范:

  • feat/xxx - 新功能
  • fix/xxx - Bug 修复
  • refactor/xxx - 重构
  • docs/xxx - 文档更新
  • test/xxx - 测试相关

2. 遵循项目规范

本项目遵循严格的工程规范，详见 CLAUDE.md。关键原则：

  • 模块优先: 每个功能都应是独立模块，清晰的边界
  • 接口优先: 模块暴露最小化的公共 API
  • 函数式优先: 优先使用纯函数，显式管理副作用
  • 类型安全: 使用 TypeScript strict 模式，避免 any
  • i18n 规范:
    • 所有用户可见文本必须使用 useI18n() 的 t() 函数
    • 同时更新 locales/zh_CN.json 和 locales/en_US.json
    • 使用描述性的翻译键名

代码风格:

  • 使用 ESLint 和 Prettier（项目已配置）
  • 组件保持小而专注，业务逻辑放在 utils/ 或 hooks/
  • 避免重复代码，2 次以上使用时提取共享逻辑

3. 添加测试（如适用）

# 运行测试
pnpm test

# 监听模式
pnpm test:watch

# 生成覆盖率报告
pnpm test:coverage

测试优先级:

  • 高: 工具函数、数据转换、存储工具、消息处理器
  • 中: 复杂 hooks、状态管理
  • 低: 展示型 UI 组件（可手动测试）

4. 提交代码

使用语义化提交消息（英文）:

# 格式: <type>: <description>

# 示例:
git commit -m "feat: add batch scraping filter presets"
git commit -m "fix: resolve language detection issue on first launch"
git commit -m "refactor: extract AI service into reusable hook"
git commit -m "docs: update i18n contribution guide"

提交类型:

  • feat: 新功能
  • fix: Bug 修复
  • refactor: 重构（不改变外部行为）
  • docs: 文档更新
  • test: 测试相关
  • chore: 构建/工具相关
  • style: 代码风格（不影响逻辑）

5. 推送并创建 PR

# 推送到您的 Fork
git push origin feat/your-feature-name

# 在 GitHub 上创建 PR 到 dev 分支

PR 检查清单:

  • 代码遵循项目规范（见 CLAUDE.md）
  • 通过 pnpm lint 检查
  • 添加了必要的测试（如适用）
  • 测试通过 (pnpm test)
  • 如有新的用户可见文本，已添加翻译到两个语言文件
  • 更新了相关文档（如适用）
  • PR 描述清晰说明了更改内容和原因
  • PR 目标分支是 dev（不是 main）

PR 模板

## 更改类型

- [ ] 新功能
- [ ] Bug 修复
- [ ] 重构
- [ ] 文档更新
- [ ] 其他

## 更改描述

（清晰描述本次更改的内容和原因）

## 相关 Issue

Closes #123
Relates to #456

## 测试

（描述如何测试本次更改）

- [ ] 添加了单元测试
- [ ] 手动测试通过
- [ ] 测试了两种语言（如涉及 UI 更改）

## 截图（如适用）

（添加截图展示 UI 变化）

## 检查清单

- [ ] 代码遵循项目规范
- [ ] 通过 lint 检查
- [ ] 添加了必要的测试
- [ ] 更新了文档
- [ ] 添加了翻译（如涉及 UI 文本）

📚 文档贡献

文档改进同样重要！

文档位置:

  • 项目文档: docs/ 目录
  • 开发规范: CLAUDE.md
  • 用户文档: README.md 和 README.en.md

提交文档 PR:

  1. Fork 项目
  2. 编辑相关文档
  3. 提交 PR 到 dev 分支

文档风格:

  • 清晰、简洁、易懂
  • 提供代码示例
  • 保持中英文文档同步更新

开发规范详解

模块组织

项目采用 模块优先 的架构：

src/
├── components/      # React UI 组件
├── hooks/           # 自定义 React hooks
├── utils/           # 核心业务逻辑和工具函数
├── background/      # 后台脚本和消息处理
├── contents/        # 内容脚本（注入页面）
├── constants/       # 常量和类型定义
└── locales/         # 翻译文件

文件命名

  • Barrel 导出: index.ts（模块有多个相关导出时）
  • 单一导出: 匹配文件名 (useIsMobile.ts)
  • React 组件: PascalCase (ContentDisplay.tsx)
  • 工具函数: camelCase (extractor.ts, storage.ts)

i18n 使用规范

在组件中:

import { useI18n } from "~utils/i18n";

function MyComponent() {
  const { t } = useI18n();
  return <button>{t("common.ok")}</button>;
}

添加新翻译:

  1. 在 locales/zh_CN.json 添加键值
  2. 在 locales/en_US.json 添加对应翻译
  3. 在代码中使用 t("new.key")
  4. 测试两种语言

详见 i18n 开发者指南。

Chrome Extension 最佳实践

  • 处理异步操作时检查错误
  • 清理事件监听器
  • 使用 chrome.runtime.lastError 检查错误
  • 避免在 content scripts 中执行长时间运行的任务

行为准则

为了维护友好、包容的社区，所有贡献者应遵守以下准则：

我们的承诺

  • 尊重所有贡献者 - 无论技术水平、背景或经验
  • 建设性反馈 - 友善、有帮助的代码审查和讨论
  • 包容友善 - 欢迎不同观点和想法
  • 专注于项目目标 - 保持讨论相关和专业

不可接受的行为

  • 攻击性、侮辱性或贬低性言论
  • 人身攻击或政治攻击
  • 公开或私下骚扰
  • 未经许可发布他人隐私信息
  • 其他不专业或不受欢迎的行为

版本发布

项目采用 语义化版本:

  • 主版本号: 不兼容的 API 修改
  • 次版本号: 向下兼容的功能性新增
  • 修订号: 向下兼容的问题修正

发布流程:

  1. PR 合并到 dev 分支进行开发和测试
  2. 稳定后合并到 main 分支
  3. 创建 GitHub Release 和版本标签
  4. 发布到 Chrome Web Store

资源链接

项目相关

文档

技术栈

学习资源

常见问题

Q: 我是第一次贡献开源项目，应该从哪里开始？

A: 翻译贡献是很好的起点！您不需要编程经验，只需要熟悉目标语言。查看 i18n 指南 开始。

Q: 我可以直接联系项目维护者吗？

A: 对于项目相关的问题，请优先使用 GitHub Issues 或 Discussions，这样其他人也能看到和参与讨论。对于私密问题，欢迎发送邮件到 i@cosine.ren。

致谢

感谢所有为 Moe Copy AI 做出贡献的开发者和用户！

特别感谢:

  • @yusixian - 项目作者
  • @hyoban - 批量抓取功能贡献者
  • @XueHua-s - htmlToMarkdown 重构贡献者
  • 所有提交 Issue、PR 和反馈的朋友们！

您的贡献让 Moe Copy AI 变得更好！🎉

准备好开始贡献了吗？

期待您的参与！